Define GitObjectTypeString and update Object to use it

EliahKagan · EliahKagan · commit 1fe4dc88dcab · 2024-03-10T14:09:13.000-04:00
This is equivalent to the old Lit_commit_ish union; it is the type
of a literal string that has one of the four values that represent
actual git object types. The old Lit_commit_ish union was only used
in one place in GitPython: to annotate Object.type.

This replaces that and updates its docstring, as well as the Object
class docstring.

(One change in the Object class docstring--adding a mention of the
RootModule subclass of Submodule--is not conceptually related to
these other changes.)
diff --git a/git/objects/base.py b/git/objects/base.py
@@ -16,7 +16,7 @@
 
 from typing import Any, TYPE_CHECKING, Union
 
-from git.types import PathLike, Old_commit_ish, Lit_old_commit_ish
+from git.types import GitObjectTypeString, Old_commit_ish, PathLike
 
 if TYPE_CHECKING:
     from git.repo import Repo
@@ -36,7 +36,7 @@
 class Object(LazyMixin):
     """Base class for classes representing git object types.
 
-    The following leaf classes represent specific kinds of git objects:
+    The following four leaf classes represent specific kinds of git objects:
 
     * :class:`Blob <git.objects.blob.Blob>`
     * :class:`Tree <git.objects.tree.Tree>`
@@ -53,12 +53,14 @@ class Object(LazyMixin):
     * "tag object": https://git-scm.com/docs/gitglossary#def_tag_object
 
     :note:
-        See the :class:`~git.types.Old_commit_ish` union type.
+        See the :class:`~git.types.AnyGitObject` union type of the four leaf subclasses
+        that represent actual git object types.
 
     :note:
         :class:`~git.objects.submodule.base.Submodule` is defined under the hierarchy
         rooted at this :class:`Object` class, even though submodules are not really a
-        type of git object.
+        type of git object. (This also applies to its
+        :class:`~git.objects.submodule.root.RootModule` subclass.)
 
     :note:
         This :class:`Object` class should not be confused with :class:`object` (the root
@@ -77,7 +79,7 @@ class Object(LazyMixin):
 
     __slots__ = ("repo", "binsha", "size")
 
-    type: Union[Lit_old_commit_ish, None] = None
+    type: Union[GitObjectTypeString, None] = None
     """String identifying (a concrete :class:`Object` subtype for) a git object type.
 
     The subtypes that this may name correspond to the kinds of git objects that exist,
@@ -90,7 +92,7 @@ class Object(LazyMixin):
         ``None`` in concrete leaf subclasses representing specific git object types.
 
     :note:
-        See also :class:`~git.types.Old_commit_ish`.
+        See also :class:`~git.types.GitObjectTypeString`.
     """
 
     def __init__(self, repo: "Repo", binsha: bytes):
diff --git a/git/types.py b/git/types.py
@@ -114,6 +114,18 @@
     object types.
 """
 
+GitObjectTypeString = Literal["commit", "tag", "blob", "tree"]
+"""Literal strings identifying git object types and the
+:class:`~git.objects.base.Object`-based types that represent them.
+
+See the :attr:`Object.type <git.objects.base.Object.type>` attribute. These are its
+values in :class:`~git.objects.base.Object` subclasses that represent git objects. These
+literals therefore correspond to the types in the :class:`AnyGitObject` union.
+
+These are the same strings git itself uses to identify its four object types. See
+gitglossary(7) on "object type": https://git-scm.com/docs/gitglossary#def_object_type
+"""
+
 # FIXME: Replace uses with AnyGitObject and Commit_ish, and remove this.
 Old_commit_ish = Union["Commit", "TagObject", "Blob", "Tree"]
 """Union of the :class:`~git.objects.base.Object`-based types that represent git object
@@ -140,6 +152,8 @@
     compatibility.
 """
 
+# FIXME: After replacing the one use with GitObjectTypeString, define Lit_commit_ish
+#        somehow (it is a breaking change to remove it entirely). Maybe deprecate it.
 Lit_old_commit_ish = Literal["commit", "tag", "blob", "tree"]
 """Literal strings identifying concrete :class:`~git.objects.base.Object` subtypes
 representing git object types.
