Mark type aliases with `TypeAlias` (#12658)

sphinx/_cli/__init__.py

@@ -36,10 +36,10 @@ from sphinx.locale import __, init_console
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Sequence
-    from typing import NoReturn
+    from typing import NoReturn, TypeAlias
 
-    _PARSER_SETUP = Callable[[argparse.ArgumentParser], argparse.ArgumentParser]
-    _RUNNER = Callable[[argparse.Namespace], int]
+    _PARSER_SETUP: TypeAlias = Callable[[argparse.ArgumentParser], argparse.ArgumentParser]
+    _RUNNER: TypeAlias = Callable[[argparse.Namespace], int]
 
     from typing import Protocol
 

sphinx/builders/html/__init__.py

@@ -51,6 +51,7 @@ from sphinx.writers.html5 import HTML5Translator
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator, Set
+    from typing import TypeAlias
 
     from docutils.nodes import Node
     from docutils.readers import Reader
@@ -67,7 +68,7 @@ INVENTORY_FILENAME = 'objects.inv'
 logger = logging.getLogger(__name__)
 return_codes_re = re.compile('[\r\n]+')
 
-DOMAIN_INDEX_TYPE = tuple[
+DOMAIN_INDEX_TYPE: TypeAlias = tuple[
     # Index name (e.g. py-modindex)
     str,
     # Index class

sphinx/config.py

@@ -25,6 +25,7 @@ else:
 if TYPE_CHECKING:
     import os
     from collections.abc import Collection, Iterator, Sequence, Set
+    from typing import TypeAlias
 
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
@@ -33,7 +34,7 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-_ConfigRebuild = Literal[
+_ConfigRebuild: TypeAlias = Literal[
     '', 'env', 'epub', 'gettext', 'html',
     # sphinxcontrib-applehelp
     'applehelp',
@@ -93,7 +94,7 @@ class ENUM:
             return value in self.candidates
 
 
-_OptValidTypes = tuple[()] | tuple[type, ...] | frozenset[type] | ENUM
+_OptValidTypes: TypeAlias = tuple[()] | tuple[type, ...] | frozenset[type] | ENUM
 
 
 class _Opt:

sphinx/domains/__init__.py

@@ -18,6 +18,7 @@ from sphinx.locale import _
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
+    from typing import TypeAlias
 
     from docutils import nodes
     from docutils.parsers.rst import Directive
@@ -154,7 +155,7 @@ class Index(ABC):
         raise NotImplementedError
 
 
-TitleGetter = Callable[[Node], str | None]
+TitleGetter: TypeAlias = Callable[[Node], str | None]
 
 
 class Domain:

sphinx/domains/c/_ast.py

@@ -12,18 +12,20 @@ from sphinx.util.cfamily import (
     ASTAttributeList,
     ASTBaseBase,
     ASTBaseParenExprList,
-    StringifyTransform,
     UnsupportedMultiCharacterCharLiteral,
     verify_description_mode,
 )
 
 if TYPE_CHECKING:
+    from typing import TypeAlias
+
     from docutils.nodes import Element, Node, TextElement
 
     from sphinx.domains.c._symbol import Symbol
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.cfamily import StringifyTransform
 
-DeclarationType = Union[  # NoQA: UP007
+DeclarationType: TypeAlias = Union[  # NoQA: UP007
     "ASTStruct", "ASTUnion", "ASTEnum", "ASTEnumerator",
     "ASTType", "ASTTypeWithInit", "ASTMacro",
 ]

sphinx/domains/cpp/_ast.py

@@ -24,7 +24,6 @@ from sphinx.util.cfamily import (
     ASTBaseBase,
     ASTBaseParenExprList,
     NoOldIdError,
-    StringifyTransform,
     UnsupportedMultiCharacterCharLiteral,
     verify_description_mode,
 )
@@ -35,6 +34,7 @@ if TYPE_CHECKING:
     from sphinx.addnodes import desc_signature
     from sphinx.domains.cpp._symbol import Symbol
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.cfamily import StringifyTransform
 
 
 class ASTBase(ASTBaseBase):

sphinx/environment/adapters/indexentries.py

@@ -30,7 +30,7 @@ if TYPE_CHECKING:
         _IndexEntrySubItems,
         _IndexEntryCategoryKey,
     ]
-    _IndexEntryMap = dict[str, _IndexEntry]
+    _IndexEntryMap: TypeAlias = dict[str, _IndexEntry]
     _Index: TypeAlias = list[
         tuple[
             str,

sphinx/ext/intersphinx/_shared.py

@@ -7,6 +7,8 @@ from typing import TYPE_CHECKING, Final
 from sphinx.util import logging
 
 if TYPE_CHECKING:
+    from typing import TypeAlias
+
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import Inventory
 
@@ -27,7 +29,7 @@ if TYPE_CHECKING:
     InventoryLocation = str | None
 
     #: Inventory cache entry. The integer field is the cache expiration time.
-    InventoryCacheEntry = tuple[InventoryName, int, Inventory]
+    InventoryCacheEntry: TypeAlias = tuple[InventoryName, int, Inventory]
 
     #: The type of :confval:`intersphinx_mapping` *after* normalization.
     IntersphinxMapping = dict[

sphinx/util/cfamily.py

@@ -3,9 +3,8 @@
 from __future__ import annotations
 
 import re
-from collections.abc import Callable
 from copy import deepcopy
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 
@@ -13,17 +12,17 @@ from sphinx import addnodes
 from sphinx.util import logging
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
+    from typing import Any, TypeAlias
 
     from docutils.nodes import TextElement
 
     from sphinx.config import Config
 
+    StringifyTransform: TypeAlias = Callable[[Any], str]
+
 logger = logging.getLogger(__name__)
 
-StringifyTransform = Callable[[Any], str]
-
-
 _whitespace_re = re.compile(r'\s+')
 anon_identifier_re = re.compile(r'(@[a-zA-Z0-9_])[a-zA-Z0-9_]*\b')
 identifier_re = re.compile(r'''

sphinx/util/i18n.py

@@ -20,7 +20,7 @@ from sphinx.util.osutil import SEP, canon_path, relpath
 if TYPE_CHECKING:
     import datetime as dt
     from collections.abc import Iterator
-    from typing import Protocol
+    from typing import Protocol, TypeAlias
 
     from babel.core import Locale
 
@@ -52,7 +52,7 @@ if TYPE_CHECKING:
             locale: str | Locale | None = ...,
         ) -> str: ...
 
-    Formatter = DateFormatter | TimeFormatter | DatetimeFormatter
+    Formatter: TypeAlias = DateFormatter | TimeFormatter | DatetimeFormatter
 
 logger = logging.getLogger(__name__)
 

sphinx/util/typing.py

@@ -81,13 +81,13 @@ def is_invalid_builtin_class(obj: Any) -> bool:
 
 
 # Text like nodes which are initialized with text and rawsource
-TextlikeNode = nodes.Text | nodes.TextElement
+TextlikeNode: TypeAlias = nodes.Text | nodes.TextElement
 
 # type of None
-NoneType = type(None)
+NoneType: TypeAlias = type(None)  # type: ignore[no-redef]
 
 # path matcher
-PathMatcher = Callable[[str], bool]
+PathMatcher: TypeAlias = Callable[[str], bool]
 
 # common role functions
 if TYPE_CHECKING:
@@ -105,27 +105,25 @@ if TYPE_CHECKING:
         ) -> tuple[list[nodes.Node], list[nodes.system_message]]:
             ...
 else:
-    RoleFunction = Callable[
+    RoleFunction: TypeAlias = Callable[
         [str, str, str, int, Inliner, dict[str, Any], Sequence[str]],
         tuple[list[nodes.Node], list[nodes.system_message]],
     ]
 
 # A option spec for directive
-OptionSpec = dict[str, Callable[[str], Any]]
+OptionSpec: TypeAlias = dict[str, Callable[[str], Any]]
 
 # title getter functions for enumerable nodes (see sphinx.domains.std)
-TitleGetter = Callable[[nodes.Node], str]
+TitleGetter: TypeAlias = Callable[[nodes.Node], str]
 
 # inventory data on memory
-InventoryItem = tuple[
+InventoryItem: TypeAlias = tuple[
     str,  # project name
     str,  # project version
     str,  # URL
     str,  # display name
 ]
-
-# referencable role -> (reference name -> inventory item)
-Inventory = dict[str, dict[str, InventoryItem]]
+Inventory: TypeAlias = dict[str, dict[str, InventoryItem]]
 
 
 class ExtensionMetadata(TypedDict, total=False):
@@ -149,7 +147,7 @@ class ExtensionMetadata(TypedDict, total=False):
 
 
 if TYPE_CHECKING:
-    _ExtensionSetupFunc = Callable[[Sphinx], ExtensionMetadata]
+    _ExtensionSetupFunc: TypeAlias = Callable[[Sphinx], ExtensionMetadata]
 
 
 def get_type_hints(

tests/test_config/test_config.py

@@ -25,9 +25,10 @@ from sphinx.errors import ConfigError, ExtensionError, VersionRequirementError
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
+    from typing import TypeAlias
 
-    CircularList = list[int | 'CircularList']
-    CircularDict = dict[str, int | 'CircularDict']
+    CircularList: TypeAlias = list[int | 'CircularList']
+    CircularDict: TypeAlias = dict[str, int | 'CircularDict']
 
 
 def check_is_serializable(subject: object, *, circular: bool) -> None:

utils/bump_version.py

@@ -8,10 +8,11 @@ import sys
 import time
 from contextlib import contextmanager
 from pathlib import Path
-from typing import TYPE_CHECKING, TypeAlias
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence
+    from typing import TypeAlias
 
 script_dir = Path(__file__).parent
 package_dir = script_dir.parent