TYP: Annotate deprecation and versioning machinery

Author: effigies

nibabel/deprecated.py

@@ -2,12 +2,15 @@
 """
 from __future__ import annotations
 
+import typing as ty
 import warnings
-from typing import Type
 
 from .deprecator import Deprecator
 from .pkg_info import cmp_pkg_version
 
+if ty.TYPE_CHECKING:  # pragma: no cover
+    P = ty.ParamSpec('P')
+
 
 class ModuleProxy:
     """Proxy for module that may not yet have been imported
@@ -30,14 +33,14 @@ class ModuleProxy:
     module.
     """
 
-    def __init__(self, module_name):
+    def __init__(self, module_name: str):
         self._module_name = module_name
 
-    def __getattr__(self, key):
+    def __getattr__(self, key: str) -> ty.Any:
         mod = __import__(self._module_name, fromlist=[''])
         return getattr(mod, key)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f'<module proxy for {self._module_name}>'
 
 
@@ -60,7 +63,7 @@ class FutureWarningMixin:
 
     warn_message = 'This class will be removed in future versions'
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: P.args, **kwargs: P.kwargs) -> None:
         warnings.warn(self.warn_message, FutureWarning, stacklevel=2)
         super().__init__(*args, **kwargs)
 
@@ -85,12 +88,12 @@ def alert_future_error(
     msg: str,
     version: str,
     *,
-    warning_class: Type[Warning] = FutureWarning,
-    error_class: Type[Exception] = RuntimeError,
+    warning_class: type[Warning] = FutureWarning,
+    error_class: type[Exception] = RuntimeError,
     warning_rec: str = '',
     error_rec: str = '',
     stacklevel: int = 2,
-):
+) -> None:
     """Warn or error with appropriate messages for changing functionality.
 
     Parameters

nibabel/deprecator.py

@@ -1,10 +1,16 @@
 """Class for recording and reporting deprecations
 """
+from __future__ import annotations
 
 import functools
 import re
+import typing as ty
 import warnings
 
+if ty.TYPE_CHECKING:  # pragma: no cover
+    T = ty.TypeVar('T')
+    P = ty.ParamSpec('P')
+
 _LEADING_WHITE = re.compile(r'^(\s*)')
 
 TESTSETUP = """
@@ -38,15 +44,20 @@ class ExpiredDeprecationError(RuntimeError):
     pass
 
 
-def _ensure_cr(text):
+def _ensure_cr(text: str) -> str:
     """Remove trailing whitespace and add carriage return
 
     Ensures that `text` always ends with a carriage return
     """
     return text.rstrip() + '\n'
 
 
-def _add_dep_doc(old_doc, dep_doc, setup='', cleanup=''):
+def _add_dep_doc(
+    old_doc: str,
+    dep_doc: str,
+    setup: str = '',
+    cleanup: str = '',
+) -> str:
     """Add deprecation message `dep_doc` to docstring in `old_doc`
 
     Parameters
@@ -55,6 +66,10 @@ def _add_dep_doc(old_doc, dep_doc, setup='', cleanup=''):
         Docstring from some object.
     dep_doc : str
         Deprecation warning to add to top of docstring, after initial line.
+    setup : str, optional
+        Doctest setup text
+    cleanup : str, optional
+        Doctest teardown text
 
     Returns
     -------
@@ -76,7 +91,9 @@ def _add_dep_doc(old_doc, dep_doc, setup='', cleanup=''):
     if next_line >= len(old_lines):
         # nothing following first paragraph, just append message
         return old_doc + '\n' + dep_doc
-    indent = _LEADING_WHITE.match(old_lines[next_line]).group()
+    leading_white = _LEADING_WHITE.match(old_lines[next_line])
+    assert leading_white is not None  # Type narrowing, since this always matches
+    indent = leading_white.group()
     setup_lines = [indent + L for L in setup.splitlines()]
     dep_lines = [indent + L for L in [''] + dep_doc.splitlines() + ['']]
     cleanup_lines = [indent + L for L in cleanup.splitlines()]
@@ -113,15 +130,15 @@ class Deprecator:
 
     def __init__(
         self,
-        version_comparator,
-        warn_class=DeprecationWarning,
-        error_class=ExpiredDeprecationError,
-    ):
+        version_comparator: ty.Callable[[str], int],
+        warn_class: type[Warning] = DeprecationWarning,
+        error_class: type[Exception] = ExpiredDeprecationError,
+    ) -> None:
         self.version_comparator = version_comparator
         self.warn_class = warn_class
         self.error_class = error_class
 
-    def is_bad_version(self, version_str):
+    def is_bad_version(self, version_str: str) -> bool:
         """Return True if `version_str` is too high
 
         Tests `version_str` with ``self.version_comparator``
@@ -139,7 +156,14 @@ def is_bad_version(self, version_str):
         """
         return self.version_comparator(version_str) == -1
 
-    def __call__(self, message, since='', until='', warn_class=None, error_class=None):
+    def __call__(
+        self,
+        message: str,
+        since: str = '',
+        until: str = '',
+        warn_class: type[Warning] | None = None,
+        error_class: type[Exception] | None = None,
+    ) -> ty.Callable[[ty.Callable[P, T]], ty.Callable[P, T]]:
         """Return decorator function function for deprecation warning / error
 
         Parameters
@@ -164,8 +188,8 @@ def __call__(self, message, since='', until='', warn_class=None, error_class=Non
         deprecator : func
             Function returning a decorator.
         """
-        warn_class = warn_class or self.warn_class
-        error_class = error_class or self.error_class
+        exception = error_class if error_class is not None else self.error_class
+        warning = warn_class if warn_class is not None else self.warn_class
         messages = [message]
         if (since, until) != ('', ''):
             messages.append('')
@@ -174,19 +198,21 @@ def __call__(self, message, since='', until='', warn_class=None, error_class=Non
         if until:
             messages.append(
                 f"* {'Raises' if self.is_bad_version(until) else 'Will raise'} "
-                f'{error_class} as of version: {until}'
+                f'{exception} as of version: {until}'
             )
         message = '\n'.join(messages)
 
-        def deprecator(func):
+        def deprecator(func: ty.Callable[P, T]) -> ty.Callable[P, T]:
             @functools.wraps(func)
-            def deprecated_func(*args, **kwargs):
+            def deprecated_func(*args: P.args, **kwargs: P.kwargs) -> T:
                 if until and self.is_bad_version(until):
-                    raise error_class(message)
-                warnings.warn(message, warn_class, stacklevel=2)
+                    raise exception(message)
+                warnings.warn(message, warning, stacklevel=2)
                 return func(*args, **kwargs)
 
             keep_doc = deprecated_func.__doc__
+            if keep_doc is None:
+                keep_doc = ''
             setup = TESTSETUP
             cleanup = TESTCLEANUP
             # After expiration, remove all but the first paragraph.

nibabel/pkg_info.py

@@ -14,7 +14,7 @@
 COMMIT_HASH = '$Format:%h$'
 
 
-def _cmp(a, b) -> int:
+def _cmp(a: Version, b: Version) -> int:
     """Implementation of ``cmp`` for Python 3"""
     return (a > b) - (a < b)
 
@@ -113,7 +113,7 @@ def pkg_commit_hash(pkg_path: str | None = None) -> tuple[str, str]:
     return '(none found)', '<not found>'
 
 
-def get_pkg_info(pkg_path: str) -> dict:
+def get_pkg_info(pkg_path: str) -> dict[str, str]:
     """Return dict describing the context of this package
 
     Parameters