Make NULL_TREE and Index precisely annotatable

This creates a git.diff.DiffConstants enumeration and makes the
git.diff.NULL_TREE and git.diff.Diffable.Index objects constants in
it. This allows them (including as an alternative in a union) to be
annotated as literals:

- Literal[DiffConstants.NULL_TREE]
- Literal[DIffConstants.INDEX]

Although the enumeration type must unfortunately be included in the
annotations as shown above (at least mypy requires this), using the
objects/values themselves does not require any code to change. So
this shouldn't break anything at runtime for code using GitPython,
unless it has relied on NULL_TREE being a direct instance of object,
or relied on Diffable.Index (all useful uses of which were also as
an opaque constant) being defined as a class.

More specifically, all the ways that NULL_TREE and Index could be
*accessed* before are still working, because:

- NULL_TREE is aliased at module level, where it was before.
  It is also aliased at class level in Diffable, for consistency.

- INDEX is aliased at class level in Diffable, as Index, where it
  was before. This way, Diffable.Index can still be used. It is
  also aliased, in the same scope, as INDEX. Because it is, and in
  effect has always been, a constant, the new INDEX spelling is
  preferable. But there is no major disadvantage of the old Index
  spelling, so in docstrings I have made no effort at this time to
  discourage its use. (If GitPython ever uses all-caps identifiers
  strictly as constants, then the clarity benefit of ensuring only
  the INDEX version is used will be greater, and then it might make
  sense to deprecate Index. However, this seems unlikely to happen
  as it would be a breaking change, due to the way functions like
  git.reset rebind Git.GIT_PYTHON_GIT_EXECUTABLE.) INDEX is also
  aliased at module level, for consistency.

- NULL_TREE is still included in git.diff.__all__, causing it to be
  recognized as public in git.diff and also to be accessible as an
  attribute of the top-level git module (which currently uses
  wildcard imports). For consistency, I have also included INDEX in
  __all__.

- Because there is a benefit to being able to freely referene the
  new DiffConstants enumeration in annotations (though in practice
  this may mostly be to implementers of new Diffable subclasses), I
  have also included DiffConstants in __all__. In addition, the
  name DiffConstants (rather than, e.g., Constants) should avoid
  confusion even if it ends up in another scope unexpectedly.

To avoid a situation where users/developers may erroneously think
these aliases are different from each other, I have documented the
situation in the docstrings for each, referring to the others.
(Sphinx does not automatically use the original docstring for an
aliased name introduced in this way, and there is also arguably a
clarity benefit to their differing wording, such as how each refers
*only* to the others.) Other docstings are also updated.

This commit completes the change begun in 2f5e258 before this,
resolving the one mypy error it added. But this does not complete
the larger change begun in 0e1df29:

- One of the effects of this change is to make it possible to
  annotate precisely for NULL_TREE, either by using
  Literal[DiffConstants.NULL_TREE] or consolidating it with the
  Literal[DiffConstants.INDEX] alternative by including
  DiffConstants in the union instead of either/both of them.

- But that is not yet done here, and when it is done for
  Diffable.diff, the LSP issue in IndexFile.diff, which does not
  currently accommodate NULL_TREE, will resurface (or, rather, be
  rightly revealed by mypy, in a way that is specifically clear).

Author: EliahKagan

Diff for: git/diff.py

@@ -3,6 +3,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
+import enum
 import re
 
 from git.cmd import handle_process_output
@@ -22,13 +23,12 @@
     Match,
     Optional,
     Tuple,
-    Type,
     TypeVar,
     Union,
     TYPE_CHECKING,
     cast,
 )
-from git.types import Literal, PathLike, final
+from git.types import Literal, PathLike
 
 if TYPE_CHECKING:
     from .objects.tree import Tree
@@ -48,10 +48,55 @@
 # ------------------------------------------------------------------------
 
 
-__all__ = ("Diffable", "DiffIndex", "Diff", "NULL_TREE")
+__all__ = ("DiffConstants", "NULL_TREE", "INDEX", "Diffable", "DiffIndex", "Diff")
 
-NULL_TREE = object()
-"""Special object to compare against the empty tree in diffs."""
+
+@enum.unique
+class DiffConstants(enum.Enum):
+    """Special objects for :meth:`Diffable.diff`.
+
+    See the :meth:`Diffable.diff` method's ``other`` parameter, which accepts various
+    values including these.
+
+    :note:
+        These constants are also available as attributes of the :mod:`git.diff` module,
+        the :class:`Diffable` class and its subclasses and instances, and the top-level
+        :mod:`git` module.
+    """
+
+    NULL_TREE = enum.auto()
+    """Stand-in indicating you want to compare against the empty tree in diffs.
+
+    Also accessible as :const:`git.NULL_TREE`, :const:`git.diff.NULL_TREE`, and
+    :const:`Diffable.NULL_TREE`.
+    """
+
+    INDEX = enum.auto()
+    """Stand-in indicating you want to diff against the index.
+
+    Also accessible as :const:`git.INDEX`, :const:`git.diff.INDEX`, and
+    :const:`Diffable.INDEX`, as well as :const:`Diffable.Index`. The latter has been
+    kept for backward compatibility and made an alias of this, so it may still be used.
+    """
+
+
+NULL_TREE: Literal[DiffConstants.NULL_TREE] = DiffConstants.NULL_TREE
+"""Stand-in indicating you want to compare against the empty tree in diffs.
+
+See :meth:`Diffable.diff`, which accepts this as a value of its ``other`` parameter.
+
+This is an alias of :const:`DiffConstants.NULL_TREE`, which may also be accessed as
+:const:`git.NULL_TREE` and :const:`Diffable.NULL_TREE`.
+"""
+
+INDEX: Literal[DiffConstants.INDEX] = DiffConstants.INDEX
+"""Stand-in indicating you want to diff against the index.
+
+See :meth:`Diffable.diff`, which accepts this as a value of its ``other`` parameter.
+
+This is an alias of :const:`DiffConstants.INDEX`, which may also be accessed as
+:const:`git.INDEX` and :const:`Diffable.INDEX`, as well as :const:`Diffable.Index`.
+"""
 
 _octal_byte_re = re.compile(rb"\\([0-9]{3})")
 
@@ -84,7 +129,7 @@ class Diffable:
     compatible type.
 
     :note:
-        Subclasses require a repo member, as it is the case for
+        Subclasses require a :attr:`repo` member, as it is the case for
         :class:`~git.objects.base.Object` instances. For practical reasons we do not
         derive from :class:`~git.objects.base.Object`.
     """
@@ -94,9 +139,25 @@ class Diffable:
     repo: "Repo"
     """Repository to operate on. Must be provided by subclass or sibling class."""
 
-    @final
-    class Index:
-        """Stand-in indicating you want to diff against the index."""
+    NULL_TREE = NULL_TREE
+    """Stand-in indicating you want to compare against the empty tree in diffs.
+
+    See the :meth:`diff` method, which accepts this as a value of its ``other``
+    parameter.
+
+    This is the same as :const:`DiffConstants.NULL_TREE`, and may also be accessed as
+    :const:`git.NULL_TREE` and :const:`git.diff.NULL_TREE`.
+    """
+
+    INDEX = Index = INDEX
+    """Stand-in indicating you want to diff against the index.
+
+    See the :meth:`diff` method, which accepts this as a value of its ``other``
+    parameter.
+
+    This is the same as :const:`DiffConstants.INDEX`, and may also be accessed as
+    :const:`git.INDEX` and :const:`git.diff.INDEX`.
+    """
 
     def _process_diff_args(
         self,
@@ -112,7 +173,7 @@ def _process_diff_args(
 
     def diff(
         self,
-        other: Union[Type["Index"], "Tree", "Commit", str, None] = Index,
+        other: Union[Literal[DiffConstants.INDEX], "Tree", "Commit", str, None] = INDEX,
         paths: Union[PathLike, List[PathLike], Tuple[PathLike, ...], None] = None,
         create_patch: bool = False,
         **kwargs: Any,
@@ -125,20 +186,15 @@ def diff(
 
             * If ``None``, we will be compared to the working tree.
 
-            * If :class:`~git.types.Tree_ish`, it will be compared against the
-              respective tree. (See https://git-scm.com/docs/gitglossary#def_tree-ish.)
-              This can also be passed as a string.
+            * If a :class:`~git.types.Tree_ish` or string, it will be compared against
+              the respective tree.
 
-            * If :class:`Diffable.Index`, it will be compared against the index. Use the
-              type object :class:`Index` itself, without attempting to instantiate it.
-              (That is, you should treat :class:`Index` as an opqaue constant. Don't
-              rely on it being a class or even callable.)
+            * If :const:`INDEX`, it will be compared against the index.
 
-            * If :attr:`git.NULL_TREE <NULL_TREE>`, it will compare against the empty
-              tree.
+            * If :const:`NULL_TREE`, it will compare against the empty tree.
 
-            This parameter defaults to :class:`Diffable.Index` (rather than ``None``) so
-            that the method will not by default fail on bare repositories.
+            This parameter defaults to :const:`INDEX` (rather than ``None``) so that the
+            method will not by default fail on bare repositories.
 
         :param paths:
             This a list of paths or a single path to limit the diff to. It will only
@@ -185,7 +241,7 @@ def diff(
             paths = [paths]
 
         diff_cmd = self.repo.git.diff
-        if other is Diffable.Index:
+        if other is INDEX:
             args.insert(0, "--cached")
         elif other is NULL_TREE:
             args.insert(0, "-r")  # Recursive diff-tree.
@@ -218,7 +274,7 @@ def diff(
 
 
 class DiffIndex(List[T_Diff]):
-    R"""An Index for diffs, allowing a list of :class:`Diff`\s to be queried by the diff
+    R"""An index for diffs, allowing a list of :class:`Diff`\s to be queried by the diff
     properties.
 
     The class improves the diff handling convenience.

Diff for: git/index/base.py

@@ -76,11 +76,10 @@
     Sequence,
     TYPE_CHECKING,
     Tuple,
-    Type,
     Union,
 )
 
-from git.types import Commit_ish, PathLike
+from git.types import Commit_ish, Literal, PathLike
 
 if TYPE_CHECKING:
     from subprocess import Popen
@@ -1479,7 +1478,7 @@ def reset(
     # @ default_index, breaks typing for some reason, copied into function
     def diff(
         self,
-        other: Union[Type["git_diff.Diffable.Index"], "Tree", "Commit", str, None] = git_diff.Diffable.Index,
+        other: Union[Literal[git_diff.DiffConstants.INDEX], "Tree", "Commit", str, None] = git_diff.INDEX,
         paths: Union[PathLike, List[PathLike], Tuple[PathLike, ...], None] = None,
         create_patch: bool = False,
         **kwargs: Any,

Diff for: git/types.py

@@ -22,7 +22,6 @@
         TypedDict,
         Protocol,
         SupportsIndex as SupportsIndex,
-        final,
         runtime_checkable,
     )
 else:
@@ -31,7 +30,6 @@
         SupportsIndex as SupportsIndex,
         TypedDict,
         Protocol,
-        final,
         runtime_checkable,
     )