Refine deprecated module attributes and their warnings

- In the top-level git module, import util from git.index so there
  is no ambiguity for tools in detecting which module the util
  attribute of the top-level git module (i.e., git.util in an
  *expression*) is, even though it's subsequently deleted (and then
  dynamically supplied when requested, in a way that is opaque to
  static type checkers due to being only when `not TYPE_CHECKING`).
  This seems to be necessary for some tools.

  Curiously, guarding the del statement under `not TYPE_CHECKING`
  seems *not* to be needed by any tools of any kind. It should
  still possibly be done, but that's not included in these changes.

- Add the missing deprecation warning for git.types.Lit_commit_ish.

- When importing the warnings module, do so with a top-level import
  as in the other GitPython modules that have long (and reasonably)
  done so.

  In git/__init__.py, there already had to be an import of
  importlib, which seemed like it should be done locally in case of
  delays. Neither the importlib module nor any of its submodules
  were already imported anywhere in GitPython, and the code that
  uses it will most often not be exercised. So there is a potential
  benefit to avoiding loading it when not needed.

  When writing a local import for that, I had included the warnings
  module as a local import as well. But this obscures the potential
  benefit of locally importing importlib, and could lead to
  ill-advised changes in the future based on the idea that the
  degree of justification to be local imports was the same for them
  both.

Author: EliahKagan

Diff for: git/__init__.py

@@ -93,6 +93,8 @@
 if TYPE_CHECKING:
     from types import ModuleType
 
+import warnings
+
 from gitdb.util import to_hex_sha
 
 from git.exc import (
@@ -167,6 +169,7 @@
         IndexEntry,
         IndexFile,
         StageType,
+        util,
     )
     from git.util import (  # @NoMove
         Actor,
@@ -198,12 +201,11 @@
 # the intuitive but potentially incompatible binding occurs due to the usual rules for
 # Python submodule bindings. So for now we delete that and let __getattr__ handle it.
 #
-del util  # type: ignore[name-defined]  # noqa: F821
+del util
 
 
 def _warned_import(message: str, fullname: str) -> "ModuleType":
     import importlib
-    import warnings
 
     warnings.warn(message, DeprecationWarning, stacklevel=3)
     return importlib.import_module(fullname)

Diff for: git/compat.py

@@ -13,6 +13,7 @@
 import locale
 import os
 import sys
+import warnings
 
 from gitdb.utils.encoding import force_bytes, force_text  # noqa: F401
 
@@ -48,8 +49,6 @@ def _getattr(name: str) -> Any:
     except KeyError:
         raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
 
-    import warnings
-
     warnings.warn(
         f"{__name__}.{name} and other is_<platform> aliases are deprecated. "
         "Write the desired os.name or sys.platform check explicitly instead.",

Diff for: git/types.py

@@ -17,6 +17,7 @@
     TypeVar,
     Union,
 )
+import warnings
 
 if sys.version_info >= (3, 8):
     from typing import (
@@ -150,9 +151,19 @@
 
 
 def _getattr(name: str) -> Any:
-    if name == "Lit_commit_ish":
-        return Literal["commit", "tag"]
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    if name != "Lit_commit_ish":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    warnings.warn(
+        "Lit_commit_ish is deprecated. It is currently defined as "
+        '`Literal["commit", "tag"]`, which should be used in its place if desired. It '
+        'had previously been defined as `Literal["commit", "tag", "blob", "tree"]`, '
+        "covering all four git object type strings including those that are never "
+        "commit-ish. For that, use the GitObjectTypeString type instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return Literal["commit", "tag"]
 
 
 if not TYPE_CHECKING:  # Preserve static checking for undefined/misspelled attributes.