context_management: add a type stub override to fix typing (#457)

context_management: add a type stub override to fix typing

Type checkers (mypy, pyright, et al.) don't understand the ContextManager descriptor class.
With a stub file, we can tell the type checker to treat ContextManager as a simple decorator function which is something that it understands.
from typing import reveal_type

import specfile

s = specfile.Specfile("./fedora/python-specfile.spec")

# Before: types.MethodType
# After: (allow_duplicates: bool = False, default_to_implicit_numbering: bool = False, default_source_number_digits: int = 1) -> GeneratorContextManager[Sources]
reveal_type(s.sources)
# Before: Any
# After: GeneratorContextManager[Sources]
reveal_type(s.sources())
# Before: Any
# After: Sources
reveal_type(s.sources().__enter__())
reveal_type(s.sources().content)

RELEASE NOTES BEGIN
context_management: add a type stub override to fix typing. Type checkers like mypy and pyright can now correctly determine the types for .sources(), .sections(), and the other Specfile methods that return context managers.
RELEASE NOTES END

Reviewed-by: Nikola Forró

Author: softwarefactory-project-zuul[bot]

.pre-commit-config.yaml

@@ -51,6 +51,8 @@ repos:
         args: [--show-error-codes, --ignore-missing-imports]
         additional_dependencies:
           [types-setuptools, types-requests, types-python-dateutil]
+          # This file is overridden by a type stub
+        exclude: "specfile/context_management.py"
   - repo: https://github.com/teemtee/tmt.git
     rev: 1.41.0
     hooks:

specfile/context_management.pyi

@@ -0,0 +1,25 @@
+# Copyright Contributors to the Packit project.
+# SPDX-License-Identifier: MIT
+
+import contextlib
+from collections.abc import Iterator
+from typing import Callable, Generator, ParamSpec, TypeVar
+
+_T_co = TypeVar("_T_co", covariant=True)
+_P = ParamSpec("_P")
+
+@contextlib.contextmanager
+def capture_stderr() -> Generator[list[bytes], None, None]: ...
+
+class GeneratorContextManager(contextlib._GeneratorContextManager[_T_co]):
+    def __init__(self, function: Callable[..., _T_co]) -> None: ...
+    def __del__(self) -> None: ...
+    @property
+    def content(self) -> _T_co: ...
+
+# Instead of the original descriptor class, tell the type checker to treat
+# ContextManager as a simple decorator function which is something that it
+# understands.
+def ContextManager(
+    func: Callable[_P, Iterator[_T_co]],
+) -> Callable[_P, GeneratorContextManager[_T_co]]: ...