This starts on a test.deprecation subpackage for deprecation tests.
Having these tests in a separate directory inside the test suite
may or may not be how they will ultimately be orgnaized, but it has
two advantages:

- Once all the tests are written, it should be easy to see what in
  GitPython is deprecated.

- Some deprecation warnings -- those on module or class attribute
  access -- will require the introduction of new dynamic behavior,
  and thus run the risk of breaking static type checking. So that
  should be checked for, where applicable. But currently the test
  suite has no type annotations and is not checked by mypy. Having
  deprecation-related tests under the same path will make it easier
  to enable mypy for just this part of the test suite (for now).

It is also for this latter reason that the one test so far is
written without using the GitPython test suite's existing fixtures
whose uses are harder to annotate. This may be changed if
warranted, though some of the more complex deprecation-related
tests may benefit from being written as pure pytest tests.

Although a number of deprecated features in GitPython do already
issue warnings, Diff.renamed is one of the features that does not
yet do so. So the newly introduced test will fail until that is
fixed in the next commit.

The newly introduced test would pass, but show:

    Exception ignored in: <function Popen.__del__ at 0x000002483DE14900>
    Traceback (most recent call last):
      File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.12_3.12.752.0_x64__qbz5n2kfra8p0\Lib\subprocess.py", line 1130, in __del__
        self._internal_poll(_deadstate=_maxsize)
      File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.12_3.12.752.0_x64__qbz5n2kfra8p0\Lib\subprocess.py", line 1575, in _internal_poll
        if _WaitForSingleObject(self._handle, 0) == _WAIT_OBJECT_0:
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    OSError: [WinError 6] The handle is invalid

This was due to how, at least for now, the deprecation warning
tests are not using GitPython's normal fixtures, which help clean
things up on Windows.

This adds a small amount of ad-hoc cleanup. It also moves the
acquisition of the Diff object into a pytest fixture, which can be
reused for the immediately forthcoming test that the preferred
property does not warn.

This will be even more helpful when testing a deprecated member of
the Commit class (not yet done).

+ Remove the TODO suggesting the diff not be computed from a real
  commit, since we're going to have the logic for that in use in
  forthcoming commit-specific deprecation warning tests anyway.

And that the non-deprecated recommended alternative trailers_list
and trailers_dict properties do not warn.

The test that trailers warns does not yet pass yet, because it has
not yet been made to warn.

Python warnings are exceptions, to facilitate converting them to
errors by raising them. Thus the more specific :exc: role applies
and is a better fit than the more general :class: role.

And that subclassing the strongly preferred git.util.Iterable class
does not warn.

The code this replaces in the `commit` pytest fixture seems not to
be needed anymore, and could arguably be removed now with no
further related changes. But whether it is needed depends on
subtle and sometimes nondeterministic factors, and may also vary
across Python versions.

To be safe, this replaces it with a call to the Repo instance's
close method, which is in effect more robust than what was being
done before, as it calls clear_cache on the the Git object that the
Repo object uses, does a gitdb/smmap collection, and on Windows
calls gc.collect both before and after that collection.

This may happen immediately anyway if the Repo object is not
reachable from any cycle, since the reference count should go to
zero after each of the deprecation warning tests (the fixture's
lifetime is that of the test case), and Repo.close is called in
Repo.__del__. But this makes it happen immediately even if there is
a cycle.

The other deprecation test modules this refers to don't exist yet
but will be introduced soon.

- Add type hints to test/deprecation/basic.py. As its module
  docstring (already) notes, that test module does not contain
  code where it is specifically important that it be type checked
  to verify important properties of the code under test. However,
  other test.deprecation.* modules will, and it is much more
  convenient to be able to scan the whole directory than the
  directory except for one file. (Less importantly, for the
  deprecation tests to be easily readable as a coherent whole, it
  makes sense that all, not just most, would have annotations.)

- Configure mypy in pyproject.toml so it can be run without
  arguments (mypy errors when run that way unless configured),
  where the effect is to scan the git/ directory, as was commonly
  done before, as well as the test/deprecation/ directory.

- Change the CI test workflow, as well as tox.ini, to run mypy with
  no arguments instead of passing `-p git`, so that it will scan
  both the git package as it had before and the test.deprecation
  package (due to the new pyproject.toml configuration).

- Change the readme to recommend running it that way, too.

Rather than only testing attribute access.

Because it's going to be necessary to express things in terms of it
in parametrization markings, in order for mypy to show the expected
errors for names that are available dynamically but deliberately
static type errors.

This tests that mypy considers them not to be present.

That mypy is configured with `warn_unused_ignores = true` is key,
since that is what verifies that the type errors really do occur,
based on the suppressions written for them.

Which was causing a type error.

To support the changes, this adds typing-extensions as a test
dependency, since we are now importing from it in a test module.
But this should probably be required and used conditionally based
on whether the Python version has assert_type in its typing module.

pyright still reports git.util as private, as it should.

(mypy does not, or does not by default, report private member
access. GitPython does not generally use pyright as part of
development at this time, but I am checking some code with it
during the process of writing the new tests.)

About why there are so many separate mypy suppressions even when
they could be consolidated into a smaller number in some places.

And add a docstring to document it, mainly to clarify that util is
intentionally omitted from that constant.

This makes the typing-extensions test dependency < 3.11 only, and
conditionally imports assert_type from typing or typing_extensions
depending on the Python version.

This omits strict=True, which is only supported in Python 3.10 and
later, and instead explicitly asserts that the arguments are the
same length (which is arguably better for its explicitness anyway).

And rename test_attributes to test_toplevel accordingly.

The tests are written broadly (per the style elsewhere in this test
suite), but narrowing the message-checking tests in this specific
way has the further advantage that the logic of the code under test
will be less reflected in the logic of the tests, so that bugs are
less likely to be missed by being duplicated across code and tests.

- 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.

There is no per-instance state involved in USE_SHELL, so pickling
is far less directly relevant than usual to multiprocessing: the
spawn and forkserver methods will not preserve a subsequently
changed attribute value unless side effects of loading a module (or
other unpickling of a function or its arguments that are submitted
to run on a worker subprocess) causes it to run again; the fork
method will.

This will be (automatically) the same with any combination of
metaclasses, properties, and custom descriptors as in the more
straightforward case of a simple class attribute. Subtleties arise
in the code that uses GitPython and multiprocessing, but should not
arise unintentionally from the change in implementation of USE_SHELL
done to add deprecation warnings, except possibly with respect to
whether warnings will be repeated in worker processes, which is
less important than whether the actual state is preserved.

As with other `type: ignore` comments in the deprecation tests,
mypy will detect if it is superfluous (provided warn_unused_ignores
is set to true), thereby enforcing that such code is a static type
error.

+ Use simplefilter where we can (separate from this test).

These conditional branches are kept so alternative implementations
can be examined, including if they need to be investigated to
satisfy some future requirement. But to be unittest.mock.patch
patchable, the approaches that would have a _USE_SHELL backing
attribute would be difficult to implement in a straightforward way,
which seems not to be needed or justified at this time.

Since that is not anticipated (except as an intermediate step in
development), these suppressions make sense, and they will also be
reported by mypy if the implementation changes to benefit from them
(so long as it is configured with warn_unused_ignores set to true).

With a special message when it is assigned a True value, which is
the dangerous use that underlies its deprecation.

The warnings are all DeprecationWarning.

This is with the intention of making it so that Git.USE_SHELL is
unittest.mock.patch patchable. However, while this moves in the
right direction, it can't be done this way, as the attribute is
found to be absent on the class, so when unittest.mock.patch
unpatches, it tries to delete the attribute it has set, which
fails due to the metaclass's USE_SHELL instance property having no
deleter.

This reimplements Git.USE_SHELL with no properties or descriptors.
The metaclass is still needed, but instad of defining properties it
defines __getattribute__ and __setattr__, which check for USE_SHELL
and warn, then invoke the default attribute access via super().

Likewise, in the Git class itself, a __getatttribute__ override is
introduced (not to be confused with __getattr__, which was already
present and handles attribute access when an attribute is otherwise
absent, unlike __getattribute__ which is always used). This checks
for reading USE_SHELL on an instance and warns, then invokes the
default attribute access via super().

Advantages:

- Git.USE_SHELL is again unittest.mock.patch patchable.

- AttributeError messages are automatically as before.

- It effectively is a simple attribute, yet with warning, so other
  unanticipated ways of accessing it may be less likely to break.

- The code is simpler, cleaner, and clearer. There is some
  overhead, but it is small, especially compared to a subprocess
  invocation as is done for performing most git operations.

However, this does introduce disadvantages that must be addressed:

- Although attribute access on Git instances was already highly
  dynamic, as "methods" are synthesized for git subcommands, this
  was and is not the case for the Git class itself, whose
  attributes remain exactly those that can be inferred without
  considering the existence of __getattribute__ and __setattr__ on
  the metaclass. So static type checkers need to be prevented from
  accounting for those metaclass methods in a way that causes them
  to infer that arbitrary class attribute access is allowed.

- The occurrence of Git.USE_SHELL in the Git.execute method (where
  the USE_SHELL attribute is actually examined) should be changed
  so it does not itself issue DeprecationWarning (it is not enough
  that by default a DeprecationWarning from there isn't displayed).

The existence of __getattr__ or __getattribute__ on a class causes
static type checkers like mypy to stop inferring that reads of
unrecognized instance attributes are static type errors. When the
class is a metaclass, this causes static type checkers to stop
inferring that reads of unrecognized class attributes, on classes
that use (i.e., that have as their type) the metaclass, are static
type errors.

The Git class itself defines __getattr__ and __getattribute__, but
Git objects' instance attributes really are dynamically synthesized
(in __getattr__). However, class attributes of Git are not dynamic,
even though _GitMeta defines __getattribute__. Therefore, something
special is needed so mypy infers nothing about Git class attributes
from the existence of _GitMeta.__getattribute__.

This takes the same approach as taken to the analogous problem with
__getattr__ at module level, defining __getattribute__ with a
different name first and then assigning that to __getattribute__
under an `if not TYPE_CHECKING:`. (Allowing static type checkers to
see the original definition allows them to find some kinds of type
errors in the body of the method, which is why the method isn't
just defined in the `if not TYPE_CHECKING`.)

Although it may not currently be necessary to hide __setattr__ too,
the same is done with it in _GitMeta as well. The reason is that
the intent may otherwise be subtly amgiguous to human readers and
maybe future tools: when __setattr__ exists, the effect of setting
a class attribute that did not previously exist is in principle
unclear, and might not make the attribute readble. (I am unsure if
this is the right choice; either approach seems reasonable.)

This changes how Git.execute itself accesses the USE_SHELL
attribute, so that its own read of it does not issue a warning.

Even though current type checkers don't seem to need it.

As noted in dffa930, it appears neither mypy nor pyright currently
needs `del util` to be guarded by `if not TYPE_CHECKING:` -- they
currently treat util as bound even without it, even with `del util`
present.

It is not obvious that this is the best type checker behavior or
that type checkers will continue to behave this way. (In addition,
it may help humans for all statements whose effects are intended
not to be considered for purposes of static typing to be guarded by
`if not TYPE_CHECKING:`.) So this guards the deletion of util the
same as the binding of __getattr__.

This also moves, clarifies, and expands the commented explanations
of what is going on.

In the USE_SHELL docstring:

- Restore the older wording "when executing git commands" rather
  than "to execute git commands". I've realized that longer phrase,
  which dates back to the introduction of USE_SHELL in 1c2dd54, is
  clearer, because readers less familiar with GitPython's overall
  design and operation will still not be misled into thinking
  USE_SHELL ever affects whether GitPython uses an external git
  command, versus some other mechanism, to do something.

- Give some more information about why USE_SHELL = True is unsafe
  (though further revision or clarification may be called for).

- Note some non-obvious aspects of USE_SHELL, that some of the way
  it interacts with other aspects of GitPython is not part of what
  is or has been documented about it, and in practice changes over
  time. The first example relates to gitpython-developers#1792; the second may help
  users understand why code that enables USE_SHELL on Windows, in
  addition to being unsafe there, often breaks immediately on other
  platforms; the third is included so the warnings in the expanded
  docstring are not interpreted as a new commitment that any shell
  syntax that may have a *desired* effect in some application will
  continue to have the same effect in the future.

- Cover a second application that might lead, or have led, to
  setting USE_SHELL to True, and explain what to do instead.

In test_successful_default_refresh_invalidates_cached_version_info:

- Rewrite the commented explanation of a special variant of that
  second application, where the usual easy alternatives are not
  used because part of the goal of the test is to check a "default"
  scenario that does not include either of them. This better
  explains why that choice is made in the test, and also hopefully
  will prevent anyone from thinking that test is a model for
  another situation (which, as noted, is unlikely to be the case
  even in unit tests).

And why this increases the importance of the warn_unused_ignored
mypy configuration option.

To distinguish it from the more general test.lib as well as from
the forthcoming test.deprecation.lib.

This creates a module test.deprecation.lib in the test suite for
a couple general helpers used in deprecation tests, one of which is
now used in two of the test modules and the other of which happens
only to be used in one but is concepually related to the first.

The assert_no_deprecation_warning context manager function fixes
two different flawed approaches to that, which were in use earlier:

- In test_basic, only DeprecationWarning and not the less
  significant PendingDeprecationWarning had been covere, which it
  should, at least for symmetry, since pytest.deprecated_call()
  treats it like DeprecationWarning.

  There was also a comment expressing a plan to make it filter only
  for warnings originating from GitPython, which was a flawed idea,
  as detailed below.

- In test_cmd_git, the flawed idea of attempting to filter only for
  warnings originating from GitPython was implemented. The problem
  with this is that it is heavily affected by stacklevel and its
  interaction with the pattern of calls through which the warning
  arises: warnings could actually emanate from code in GitPython's
  git module, but be registered as having come from test code, a
  callback in gitdb, smmap, or the standard library, or even the
  pytest test runner. Some of these are more likely than others,
  but all are possible especially considering the possibility of a
  bug in the value passed to warning.warn as stacklevel. (It may be
  valuable for such bugs to cause tests to fail, but they should not
  cause otherwise failing tests to wrongly pass.)

  It is probably feasible to implement such filtering successfully,
  but I don't think it's worthwhile for the small reduction in
  likelihood of failing later on an unrealted DeprecationWarning
  from somewhere else, especially considering that GitPython's main
  dependencies are so minimal.

Hopefully no one will ever need it.