Improve static typing and docstrings related to git object types

git/compat.py

@@ -3,7 +3,12 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Utilities to help provide compatibility with Python 3."""
+"""Utilities to help provide compatibility with Python 3.
+
+This module exists for historical reasons. Code outside GitPython may make use of public
+members of this module, but is unlikely to benefit from doing so. GitPython continues to
+use some of these utilities, in some cases for compatibility across different platforms.
+"""
 
 import locale
 import os

git/objects/base.py

@@ -31,15 +31,42 @@
 # --------------------------------------------------------------------------
 
 
-_assertion_msg_format = "Created object %r whose python type %r disagrees with the actual git object type %r"
+# _assertion_msg_format = "Created object %r whose python type %r disagrees with the actual git object type %r"
 
 __all__ = ("Object", "IndexObject")
 
 
 class Object(LazyMixin):
-    """An Object which may be :class:`~git.objects.blob.Blob`,
-    :class:`~git.objects.tree.Tree`, :class:`~git.objects.commit.Commit` or
-    `~git.objects.tag.TagObject`."""
+    """Base class for classes representing git object types.
+
+    The following leaf classes represent specific kinds of git objects:
+
+    * :class:`Blob <git.objects.blob.Blob>`
+    * :class:`Tree <git.objects.tree.Tree>`
+    * :class:`Commit <git.objects.commit.Commit>`
+    * :class:`TagObject <git.objects.tag.TagObject>`
+
+    See gitglossary(7) on:
+
+    * "object": https://git-scm.com/docs/gitglossary#def_object
+    * "object type": https://git-scm.com/docs/gitglossary#def_object_type
+    * "blob": https://git-scm.com/docs/gitglossary#def_blob_object
+    * "tree object": https://git-scm.com/docs/gitglossary#def_tree_object
+    * "commit object": https://git-scm.com/docs/gitglossary#def_commit_object
+    * "tag object": https://git-scm.com/docs/gitglossary#def_tag_object
+
+    :note:
+        See the :class:`git.types.Commit_ish` union type.
+
+    :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.
+
+    :note:
+        This :class:`Object` class should not be confused with :class:`object` (the root
+        of the class hierarchy in Python).
+    """
 
     NULL_HEX_SHA = "0" * 40
     NULL_BIN_SHA = b"\0" * 20
@@ -54,6 +81,20 @@ class Object(LazyMixin):
     __slots__ = ("repo", "binsha", "size")
 
     type: Union[Lit_commit_ish, 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,
+    i.e., the objects that may be present in a git repository.
+
+    :note:
+        Most subclasses represent specific types of git objects and override this class
+        attribute accordingly. This attribute is ``None`` in the :class:`Object` base
+        class, as well as the :class:`IndexObject` intermediate subclass, but never
+        ``None`` in concrete leaf subclasses representing specific git object types.
+
+    :note:
+        See also :class:`~git.types.Commit_ish`.
+    """
 
     def __init__(self, repo: "Repo", binsha: bytes):
         """Initialize an object by identifying it by its binary sha.
@@ -174,9 +215,13 @@ def stream_data(self, ostream: "OStream") -> "Object":
 
 
 class IndexObject(Object):
-    """Base for all objects that can be part of the index file, namely
-    :class:`~git.objects.tree.Tree`, :class:`~git.objects.blob.Blob` and
-    :class:`~git.objects.submodule.base.Submodule` objects."""
+    """Base for all objects that can be part of the index file.
+
+    The classes representing git object types that can be part of the index file are
+    :class:`~git.objects.tree.Tree and :class:`~git.objects.blob.Blob`. In addition,
+    :class:`~git.objects.submodule.base.Submodule`, which is not really a git object
+    type but can be part of an index file, is also a subclass.
+    """
 
     __slots__ = ("path", "mode")
 

git/objects/blob.py

@@ -12,7 +12,10 @@
 
 
 class Blob(base.IndexObject):
-    """A Blob encapsulates a git blob object."""
+    """A Blob encapsulates a git blob object.
+
+    See gitglossary(7) on "blob": https://git-scm.com/docs/gitglossary#def_blob_object
+    """
 
     DEFAULT_MIME_TYPE = "text/plain"
     type: Literal["blob"] = "blob"

git/objects/commit.py

@@ -60,8 +60,12 @@
 class Commit(base.Object, TraversableIterableObj, Diffable, Serializable):
     """Wraps a git commit object.
 
-    This class will act lazily on some of its attributes and will query the value on
-    demand only if it involves calling the git binary.
+    See gitglossary(7) on "commit object":
+    https://git-scm.com/docs/gitglossary#def_commit_object
+
+    :note:
+        This class will act lazily on some of its attributes and will query the value on
+        demand only if it involves calling the git binary.
     """
 
     # ENVIRONMENT VARIABLES

git/objects/tag.py

@@ -30,7 +30,11 @@
 
 class TagObject(base.Object):
     """Annotated (i.e. non-lightweight) tag carrying additional information about an
-    object we are pointing to."""
+    object we are pointing to.
+
+    See gitglossary(7) on "tag object":
+    https://git-scm.com/docs/gitglossary#def_tag_object
+    """
 
     type: Literal["tag"] = "tag"
 

git/objects/tree.py

@@ -162,9 +162,12 @@ def __delitem__(self, name: str) -> None:
 
 class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable):
     R"""Tree objects represent an ordered list of :class:`~git.objects.blob.Blob`\s and
-    other :class:`~git.objects.tree.Tree`\s.
+    other :class:`Tree`\s.
 
-    Tree as a list:
+    See gitglossary(7) on "tree object":
+    https://git-scm.com/docs/gitglossary#def_tree_object
+
+    Subscripting is supported, as with a list or dict:
 
     * Access a specific blob using the ``tree["filename"]`` notation.
     * You may likewise access by index, like ``blob = tree[0]``.
@@ -230,8 +233,8 @@ def join(self, file: str) -> IndexObjUnion:
         """Find the named object in this tree's contents.
 
         :return:
-            :class:`~git.objects.blob.Blob`, :class:`~git.objects.tree.Tree`,
-            or :class:`~git.objects.submodule.base.Submodule`
+            :class:`~git.objects.blob.Blob`, :class:`Tree`, or
+            :class:`~git.objects.submodule.base.Submodule`
 
         :raise KeyError:
             If the given file or tree does not exist in this tree.

git/types.py

@@ -33,85 +33,165 @@
         runtime_checkable,
     )
 
-# if sys.version_info >= (3, 10):
-#     from typing import TypeGuard  # noqa: F401
-# else:
-#     from typing_extensions import TypeGuard  # noqa: F401
-
-PathLike = Union[str, "os.PathLike[str]"]
-
 if TYPE_CHECKING:
     from git.repo import Repo
     from git.objects import Commit, Tree, TagObject, Blob
 
-    # from git.refs import SymbolicReference
+PathLike = Union[str, "os.PathLike[str]"]
+"""A :class:`str` (Unicode) based file or directory path."""
 
 TBD = Any
+"""Alias of :class:`~typing.Any`, when a type hint is meant to become more specific."""
+
 _T = TypeVar("_T")
+"""Type variable used internally in GitPython."""
 
 Tree_ish = Union["Commit", "Tree"]
+"""Union of :class:`~git.objects.base.Object`-based types that are inherently tree-ish.
+
+See gitglossary(7) on "tree-ish": https://git-scm.com/docs/gitglossary#def_tree-ish
+
+:note:
+    This union comprises **only** the :class:`~git.objects.commit.Commit` and
+    :class:`~git.objects.tree.Tree` classes, **all** of whose instances are tree-ish.
+    This is done because of the way GitPython uses it as a static type annotation.
+
+    :class:`~git.objects.tag.TagObject`, some but not all of whose instances are
+    tree-ish (those representing git tag objects that ultimately resolve to a tree or
+    commit), is not covered as part of this union type.
+"""
+
 Commit_ish = Union["Commit", "TagObject", "Blob", "Tree"]
+"""Union of the :class:`~git.objects.base.Object`-based types that represent git object
+types. This union is often usable where a commit-ish is expected, but is not actually
+limited to types representing commit-ish git objects.
+
+See gitglossary(7) on:
+
+* "commit-ish": https://git-scm.com/docs/gitglossary#def_commit-ish
+* "object type": https://git-scm.com/docs/gitglossary#def_object_type
+
+:note:
+    This union comprises **more** classes than those whose instances really represent
+    commit-ish git objects:
+
+    * A :class:`~git.objects.commit.Commit` is of course always commit-ish, and a
+      :class:`~git.objects.tag.TagObject` is commit-ish if, when peeled (recursively
+      followed), a :class:`~git.objects.commit.Commit` is obtained.
+    * However, :class:`~git.objects.blob.Blob` and :class:`~git.objects.tree.Tree` are
+      also included, and they represent git objects that are never really commit-ish.
+
+    This is an inversion of the situation with :class:`Tree_ish`, which is narrower than
+    all tree-ish objects. It is done for practical reasons including backward
+    compatibility.
+"""
+
 Lit_commit_ish = Literal["commit", "tag", "blob", "tree"]
+"""Literal strings identifying concrete :class:`~git.objects.base.Object` subtypes
+representing git object types.
+
+See the :class:`Object.type <git.objects.base.Object.type>` attribute.
+
+:note:
+    See also :class:`Commit_ish`, a union of the the :class:`~git.objects.base.Object`
+    subtypes associated with these literal strings.
+
+:note:
+    As noted in :class:`Commit_ish`, this is not limited to types of git objects that
+    are actually commit-ish.
+"""
 
 # Config_levels ---------------------------------------------------------
 
 Lit_config_levels = Literal["system", "global", "user", "repository"]
+"""Type of literal strings naming git configuration levels.
 
-# Progress parameter type alias -----------------------------------------
+These strings relate to which file a git configuration variable is in.
+"""
 
-CallableProgress = Optional[Callable[[int, Union[str, float], Union[str, float, None], str], None]]
+ConfigLevels_Tup = Tuple[Literal["system"], Literal["user"], Literal["global"], Literal["repository"]]
+"""Static type of a tuple of the four strings representing configuration levels."""
 
-# def is_config_level(inp: str) -> TypeGuard[Lit_config_levels]:
-#     # return inp in get_args(Lit_config_level)  # only py >= 3.8
-#     return inp in ("system", "user", "global", "repository")
+# Progress parameter type alias -----------------------------------------
 
+CallableProgress = Optional[Callable[[int, Union[str, float], Union[str, float, None], str], None]]
+"""General type of a progress reporter for cloning.
 
-ConfigLevels_Tup = Tuple[Literal["system"], Literal["user"], Literal["global"], Literal["repository"]]
+This is the type of a function or other callable that reports the progress of a clone,
+when passed as a ``progress`` argument to :meth:`Repo.clone <git.repo.base.Repo.clone>`
+or :meth:`Repo.clone_from <git.repo.base.Repo.clone_from>`.
+"""
 
 # -----------------------------------------------------------------------------------
 
 
 def assert_never(inp: NoReturn, raise_error: bool = True, exc: Union[Exception, None] = None) -> None:
-    """For use in exhaustive checking of literal or Enum in if/else chain.
+    """For use in exhaustive checking of a literal or enum in if/else chains.
 
-    Should only be reached if all members not handled OR attempt to pass non-members through chain.
+    A call to this function should only be reached if not all members are handled, or if
+    an attempt is made to pass non-members through the chain.
 
-    If all members handled, type is Empty. Otherwise, will cause mypy error.
+    :param inp:
+        If all members are handled, the argument for `inp` will have the
+        :class:`~typing.Never`/:class:`~typing.NoReturn` type. Otherwise, the type will
+        mismatch and cause a mypy error.
 
-    If non-members given, should cause mypy error at variable creation.
+    :param raise_error:
+        If ``True``, will also raise :class:`ValueError` with a general "unhandled
+        literal" message, or the exception object passed as `exc`.
 
-    If raise_error is True, will also raise AssertionError or the Exception passed to exc.
+    :param exc:
+        It not ``None``, this should be an already-constructed exception object, to be
+        raised if `raise_error` is ``True``.
     """
     if raise_error:
         if exc is None:
-            raise ValueError(f"An unhandled Literal ({inp}) in an if/else chain was found")
+            raise ValueError(f"An unhandled literal ({inp!r}) in an if/else chain was found")
         else:
             raise exc
 
 
 class Files_TD(TypedDict):
+    """Dictionary with stat counts for the diff of a particular file.
+
+    For the :class:`~git.util.Stats.files` attribute of :class:`~git.util.Stats`
+    objects.
+    """
+
     insertions: int
     deletions: int
     lines: int
 
 
 class Total_TD(TypedDict):
+    """Dictionary with total stats from any number of files.
+
+    For the :class:`~git.util.Stats.total` attribute of :class:`~git.util.Stats`
+    objects.
+    """
+
     insertions: int
     deletions: int
     lines: int
     files: int
 
 
 class HSH_TD(TypedDict):
+    """Dictionary carrying the same information as a :class:`~git.util.Stats` object."""
+
     total: Total_TD
     files: Dict[PathLike, Files_TD]
 
 
 @runtime_checkable
 class Has_Repo(Protocol):
+    """Protocol for having a :attr:`repo` attribute, the repository to operate on."""
+
     repo: "Repo"
 
 
 @runtime_checkable
 class Has_id_attribute(Protocol):
+    """Protocol for having :attr:`_id_attribute_` used in iteration and traversal."""
+
     _id_attribute_: str