Merge pull request gitpython-developers#1859 from EliahKagan/doc-types

Improve static typing and docstrings related to git object types

Author: Byron

.github/workflows/pythonpackage.yml

@@ -88,9 +88,12 @@ jobs:
 
     - name: Check types with mypy
       run: |
-        mypy -p git
-      # With new versions of mypy new issues might arise. This is a problem if there is nobody able to fix them,
-      # so we have to ignore errors until that changes.
+        mypy --python-version=${{ matrix.python-version }} -p git
+      env:
+        MYPY_FORCE_COLOR: "1"
+        TERM: "xterm-256color"  # For color: https://github.com/python/mypy/issues/13817
+      # With new versions of mypy new issues might arise. This is a problem if there is
+      # nobody able to fix them, so we have to ignore errors until that changes.
       continue-on-error: true
 
     - name: Test with pytest

git/__init__.py

@@ -5,38 +5,6 @@
 
 # @PydevCodeAnalysisIgnore
 
-__version__ = "git"
-
-from typing import List, Optional, Sequence, Tuple, Union, TYPE_CHECKING
-
-from gitdb.util import to_hex_sha
-from git.exc import *  # noqa: F403  # @NoMove @IgnorePep8
-from git.types import PathLike
-
-try:
-    from git.compat import safe_decode  # @NoMove @IgnorePep8
-    from git.config import GitConfigParser  # @NoMove @IgnorePep8
-    from git.objects import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.refs import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.diff import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.db import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.cmd import Git  # @NoMove @IgnorePep8
-    from git.repo import Repo  # @NoMove @IgnorePep8
-    from git.remote import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.index import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.util import (  # @NoMove @IgnorePep8
-        LockFile,
-        BlockingLockFile,
-        Stats,
-        Actor,
-        remove_password_if_present,
-        rmtree,
-    )
-except GitError as _exc:  # noqa: F405
-    raise ImportError("%s: %s" % (_exc.__class__.__name__, _exc)) from _exc
-
-# __all__ must be statically defined by py.typed support
-# __all__ = [name for name, obj in locals().items() if not (name.startswith("_") or inspect.ismodule(obj))]
 __all__ = [  # noqa: F405
     "Actor",
     "AmbiguousObjectName",
@@ -52,6 +20,7 @@
     "CommandError",
     "Commit",
     "Diff",
+    "DiffConstants",
     "DiffIndex",
     "Diffable",
     "FetchInfo",
@@ -65,18 +34,19 @@
     "HEAD",
     "Head",
     "HookExecutionError",
+    "INDEX",
     "IndexEntry",
     "IndexFile",
     "IndexObject",
     "InvalidDBRoot",
     "InvalidGitRepositoryError",
-    "List",
+    "List",  # Deprecated - import this from `typing` instead.
     "LockFile",
     "NULL_TREE",
     "NoSuchPathError",
     "ODBError",
     "Object",
-    "Optional",
+    "Optional",  # Deprecated - import this from `typing` instead.
     "ParseError",
     "PathLike",
     "PushInfo",
@@ -90,31 +60,62 @@
     "RepositoryDirtyError",
     "RootModule",
     "RootUpdateProgress",
-    "Sequence",
+    "Sequence",  # Deprecated - import from `typing`, or `collections.abc` in 3.9+.
     "StageType",
     "Stats",
     "Submodule",
     "SymbolicReference",
-    "TYPE_CHECKING",
+    "TYPE_CHECKING",  # Deprecated - import this from `typing` instead.
     "Tag",
     "TagObject",
     "TagReference",
     "Tree",
     "TreeModifier",
-    "Tuple",
-    "Union",
+    "Tuple",  # Deprecated - import this from `typing` instead.
+    "Union",  # Deprecated - import this from `typing` instead.
     "UnmergedEntriesError",
     "UnsafeOptionError",
     "UnsafeProtocolError",
     "UnsupportedOperation",
     "UpdateProgress",
     "WorkTreeRepositoryUnsupported",
+    "refresh",
     "remove_password_if_present",
     "rmtree",
     "safe_decode",
     "to_hex_sha",
 ]
 
+__version__ = "git"
+
+from typing import List, Optional, Sequence, Tuple, Union, TYPE_CHECKING
+
+from gitdb.util import to_hex_sha
+from git.exc import *  # noqa: F403  # @NoMove @IgnorePep8
+from git.types import PathLike
+
+try:
+    from git.compat import safe_decode  # @NoMove @IgnorePep8
+    from git.config import GitConfigParser  # @NoMove @IgnorePep8
+    from git.objects import *  # noqa: F403  # @NoMove @IgnorePep8
+    from git.refs import *  # noqa: F403  # @NoMove @IgnorePep8
+    from git.diff import *  # noqa: F403  # @NoMove @IgnorePep8
+    from git.db import *  # noqa: F403  # @NoMove @IgnorePep8
+    from git.cmd import Git  # @NoMove @IgnorePep8
+    from git.repo import Repo  # @NoMove @IgnorePep8
+    from git.remote import *  # noqa: F403  # @NoMove @IgnorePep8
+    from git.index import *  # noqa: F403  # @NoMove @IgnorePep8
+    from git.util import (  # @NoMove @IgnorePep8
+        LockFile,
+        BlockingLockFile,
+        Stats,
+        Actor,
+        remove_password_if_present,
+        rmtree,
+    )
+except GitError as _exc:  # noqa: F405
+    raise ImportError("%s: %s" % (_exc.__class__.__name__, _exc)) from _exc
+
 # { Initialize git executable path
 GIT_OK = None
 
@@ -146,7 +147,7 @@ def refresh(path: Optional[PathLike] = None) -> None:
     if not Git.refresh(path=path):
         return
     if not FetchInfo.refresh():  # noqa: F405
-        return  # type: ignore [unreachable]
+        return  # type: ignore[unreachable]
 
     GIT_OK = True