Enable the entire PYI category in Ruff

.ruff.toml

@@ -54,6 +54,8 @@ ignore = [
     "PLR6301",  # Method `{method_name}` could be a function, class method, or static method
     # pylint ('PLW')
     "PLW2901",  # Outer {outer_kind} variable `{name}` overwritten by inner {inner_kind} target
+    # flake8-pyi ('PYI')
+    "PYI025",  # Use `from collections.abc import Set as AbstractSet` to avoid confusion with the `set` builtin
     # flake8-bandit ('S')
     "S101",  # Use of `assert` detected
     "S110",  # `try`-`except`-`pass` detected, consider logging the exception
@@ -198,7 +200,7 @@ select = [
     "PT",
     # flake8-use-pathlib ('PTH')
       # NOT YET USED
-    # flake8-pyi ('PYI')
+    "PYI",
       # Stub files are not used in Sphinx
     # flake8-quotes ('Q')
 #    "Q000",  # Double quotes found but single quotes preferred
@@ -358,7 +360,7 @@ select = [
 
 # these tests need old ``typing`` generic aliases
 "tests/test_util/test_util_typing.py" = ["UP006", "UP007", "UP035"]
-"tests/test_util/typing_test_data.py" = ["FA100", "UP006", "UP007", "UP035"]
+"tests/test_util/typing_test_data.py" = ["FA100", "PYI030", "UP006", "UP007", "UP035"]
 
 "utils/*" = [
     "T201",  # whitelist ``print`` for stdout messages

sphinx/builders/xml.py

@@ -40,7 +40,7 @@ class XMLBuilder(Builder):
     out_suffix = '.xml'
     allow_parallel = True
 
-    _writer_class: type[XMLWriter] | type[PseudoXMLWriter] = XMLWriter
+    _writer_class: type[XMLWriter | PseudoXMLWriter] = XMLWriter
     writer: XMLWriter | PseudoXMLWriter
     default_translator_class = XMLTranslator
 

sphinx/pycode/parser.py

@@ -111,7 +111,7 @@ def __init__(
         self.end = end
         self.source = source
 
-    def __eq__(self, other: Any) -> bool:
+    def __eq__(self, other: object) -> bool:
         if isinstance(other, int):
             return self.kind == other
         elif isinstance(other, str):

sphinx/testing/fixtures.py

@@ -114,7 +114,7 @@ def app_params(
     return _app_params(args, kwargs)
 
 
-_app_params = namedtuple('_app_params', 'args,kwargs')
+_app_params = namedtuple('_app_params', 'args,kwargs')  # NoQA: PYI024
 
 
 @pytest.fixture

sphinx/util/docutils.py

@@ -30,7 +30,7 @@
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator  # NoQA: TCH003
-    from types import ModuleType
+    from types import ModuleType, TracebackType
 
     from docutils.frontend import Values
     from docutils.nodes import Element, Node, system_message
@@ -212,7 +212,10 @@ def __enter__(self) -> None:
         self.enable()
 
     def __exit__(
-        self, exc_type: type[Exception], exc_value: Exception, traceback: Any
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
     ) -> None:
         self.disable()
 

sphinx/util/inspect.py

@@ -32,15 +32,15 @@
     from typing_extensions import TypeIs
 
     class _SupportsGet(Protocol):
-        def __get__(self, __instance: Any, __owner: type | None = ...) -> Any: ...  # NoQA: E704
+        def __get__(self, instance: Any, owner: type | None = ..., /) -> Any: ...  # NoQA: E704
 
     class _SupportsSet(Protocol):
         # instance and value are contravariants but we do not need that precision
-        def __set__(self, __instance: Any, __value: Any) -> None: ...  # NoQA: E704
+        def __set__(self, instance: Any, value: Any, /) -> None: ...  # NoQA: E704
 
     class _SupportsDelete(Protocol):
         # instance is contravariant but we do not need that precision
-        def __delete__(self, __instance: Any) -> None: ...  # NoQA: E704
+        def __delete__(self, instance: Any, /) -> None: ...  # NoQA: E704
 
     _RoutineType: TypeAlias = (
         types.FunctionType
@@ -543,7 +543,7 @@ def __call__(self) -> None:
         # Dummy method to imitate special typing classes
         pass
 
-    def __eq__(self, other: Any) -> bool:
+    def __eq__(self, other: object) -> bool:
         return self.name == other
 
     def __hash__(self) -> int:

sphinx/util/osutil.py

@@ -17,7 +17,8 @@
 from sphinx.locale import __
 
 if TYPE_CHECKING:
-    from typing import Any
+    from types import TracebackType
+    from typing import Any, Self
 
 # SEP separates path elements in the canonical file names
 #
@@ -234,11 +235,14 @@ def close(self) -> None:
         with open(self._path, 'w', encoding='utf-8') as f:
             f.write(buf)
 
-    def __enter__(self) -> FileAvoidWrite:
+    def __enter__(self) -> Self:
         return self
 
     def __exit__(
-        self, exc_type: type[Exception], exc_value: Exception, traceback: Any
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
     ) -> bool:
         self.close()
         return True

sphinx/util/typing.py

@@ -126,7 +126,7 @@ def __call__(  # NoQA: E704
 
     _T_co = TypeVar('_T_co', str, bytes, covariant=True)
 
-    class _ReadableStream(Protocol[_T_co]):
+    class _ReadableStream(Protocol[_T_co]):  # NoQA: PYI046 (false positive)
         def read(self, size: int = ...) -> _T_co: ...  # NoQA: E704
 
         def __enter__(self) -> Self: ...  # NoQA: E704
@@ -170,7 +170,7 @@ class ExtensionMetadata(TypedDict, total=False):
 
 
 if TYPE_CHECKING:
-    _ExtensionSetupFunc: TypeAlias = Callable[[Sphinx], ExtensionMetadata]
+    _ExtensionSetupFunc: TypeAlias = Callable[[Sphinx], ExtensionMetadata]  # NoQA: PYI047 (false positive)
 
 
 def get_type_hints(

tests/test_extensions/test_ext_apidoc.py

@@ -8,6 +8,8 @@
 import sphinx.ext.apidoc
 from sphinx.ext.apidoc import main as apidoc_main
 
+_apidoc = namedtuple('_apidoc', 'coderoot,outdir')  # NoQA: PYI024
+
 
 @pytest.fixture
 def apidoc(rootdir, tmp_path, apidoc_params):
@@ -24,7 +26,7 @@ def apidoc(rootdir, tmp_path, apidoc_params):
         *kwargs.get('options', []),
     ]
     apidoc_main(args)
-    return namedtuple('apidoc', 'coderoot,outdir')(coderoot, outdir)
+    return _apidoc(coderoot, outdir)
 
 
 @pytest.fixture

tests/test_extensions/test_ext_napoleon.py

@@ -77,7 +77,7 @@ def __special_undoc__(self):  # NoQA: PLW3201
         pass
 
 
-SampleNamedTuple = namedtuple('SampleNamedTuple', 'user_id block_type def_id')
+SampleNamedTuple = namedtuple('SampleNamedTuple', 'user_id block_type def_id')  # NoQA: PYI024
 
 
 class TestProcessDocstring:

tests/test_extensions/test_ext_napoleon_docstring.py

@@ -26,7 +26,7 @@
 from tests.test_extensions.ext_napoleon_pep526_data_numpy import PEP526NumpyClass
 
 
-class NamedtupleSubclass(namedtuple('NamedtupleSubclass', ('attr1', 'attr2'))):
+class NamedtupleSubclass(namedtuple('NamedtupleSubclass', ('attr1', 'attr2'))):  # NoQA: PYI024
     """Sample namedtuple subclass
 
     Attributes