Explain the approach in test.deprecation to static checking

EliahKagan · EliahKagan · commit b51b08052821 · 2024-03-29T19:52:52.000-04:00
And why this increases the importance of the warn_unused_ignored
mypy configuration option.
diff --git a/pyproject.toml b/pyproject.toml
@@ -25,7 +25,7 @@ files = ["git/", "test/deprecation/"]
 disallow_untyped_defs = true
 no_implicit_optional = true
 warn_redundant_casts = true
-warn_unused_ignores = true
+warn_unused_ignores = true  # Useful in general, but especially in test/deprecation.
 warn_unreachable = true
 implicit_reexport = true
 # strict = true
diff --git a/test/deprecation/__init__.py b/test/deprecation/__init__.py
@@ -1,2 +1,19 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Tests of deprecation warnings and possible related attribute bugs.
+
+Most deprecation warnings are "basic" in the sense that there is no special complexity
+to consider, in introducing them. However, to issue deprecation warnings on mere
+attribute access can involve adding new dynamic behavior. This can lead to subtle bugs
+or less useful dynamic metadata. It can also weaken static typing, as happens if a type
+checker sees a method like ``__getattr__`` in a module or class whose attributes it did
+not already judge to be dynamic. This test.deprecation submodule covers all three cases:
+the basic cases, subtle dynamic behavior, and subtle static type checking issues.
+
+Static type checking is "tested" by a combination of code that should not be treated as
+a type error but would be in the presence of particular bugs, and code that *should* be
+treated as a type error and is accordingly marked ``# type: ignore[REASON]`` (for
+specific ``REASON``. The latter will only produce mypy errors when the expectation is
+not met if it is configured with ``warn_unused_ignores = true``.
+"""
diff --git a/test/deprecation/test_cmd_git.py b/test/deprecation/test_cmd_git.py
@@ -1,7 +1,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-"""Tests for static and dynamic characteristics of Git class and instance attributes.
+"""Tests for dynamic and static characteristics of Git class and instance attributes.
 
 Currently this all relates to the deprecated :attr:`Git.USE_SHELL` class attribute,
 which can also be accessed through instances. Some tests directly verify its behavior,
