Sphinx 7.3.6__py3-none-any.whl → 7.4.0__py3-none-any.whl

sphinx/util/typing.py

@@ -8,23 +8,45 @@ import typing
 from collections.abc import Sequence
 from contextvars import Context, ContextVar, Token
 from struct import Struct
-from typing import TYPE_CHECKING, Any, Callable, ForwardRef, TypedDict, TypeVar, Union
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Callable,
+    ForwardRef,
+    TypedDict,
+    TypeVar,
+    Union,
+)
 
 from docutils import nodes
 from docutils.parsers.rst.states import Inliner
 
 if TYPE_CHECKING:
-    import enum
+    from collections.abc import Mapping
+    from typing import Final, Literal, Protocol
+
+    from typing_extensions import TypeAlias, TypeIs
 
     from sphinx.application import Sphinx
 
+    _RestifyMode: TypeAlias = Literal[
+        'fully-qualified-except-typing',
+        'smart',
+    ]
+    _StringifyMode: TypeAlias = Literal[
+        'fully-qualified-except-typing',
+        'fully-qualified',
+        'smart',
+    ]
+
 if sys.version_info >= (3, 10):
     from types import UnionType
 else:
     UnionType = None
 
 # classes that have an incorrect .__module__ attribute
-_INVALID_BUILTIN_CLASSES = {
+_INVALID_BUILTIN_CLASSES: Final[Mapping[object, str]] = {
     Context: 'contextvars.Context',  # Context.__module__ == '_contextvars'
     ContextVar: 'contextvars.ContextVar',  # ContextVar.__module__ == '_contextvars'
     Token: 'contextvars.Token',  # Token.__module__ == '_contextvars'
@@ -71,8 +93,25 @@ NoneType = type(None)
 PathMatcher = Callable[[str], bool]
 
 # common role functions
-RoleFunction = Callable[[str, str, str, int, Inliner, dict[str, Any], Sequence[str]],
-                        tuple[list[nodes.Node], list[nodes.system_message]]]
+if TYPE_CHECKING:
+    class RoleFunction(Protocol):
+        def __call__(
+            self,
+            name: str,
+            rawtext: str,
+            text: str,
+            lineno: int,
+            inliner: Inliner,
+            /,
+            options: dict[str, Any] | None = None,
+            content: Sequence[str] = (),
+        ) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+            ...
+else:
+    RoleFunction = 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]]
@@ -115,7 +154,9 @@ if TYPE_CHECKING:
 
 
 def get_type_hints(
-    obj: Any, globalns: dict[str, Any] | None = None, localns: dict[str, Any] | None = None,
+    obj: Any,
+    globalns: dict[str, Any] | None = None,
+    localns: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Return a dictionary containing type hints for a function, method, module or class
     object.
@@ -147,8 +188,36 @@ def is_system_TypeVar(typ: Any) -> bool:
     return modname == 'typing' and isinstance(typ, TypeVar)
 
 
-def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> str:
-    """Convert python class to a reST reference.
+def _is_annotated_form(obj: Any) -> TypeIs[Annotated[Any, ...]]:
+    """Check if *obj* is an annotated type."""
+    return typing.get_origin(obj) is Annotated or str(obj).startswith('typing.Annotated')
+
+
+def _is_unpack_form(obj: Any) -> bool:
+    """Check if the object is :class:`typing.Unpack` or equivalent."""
+    if sys.version_info >= (3, 11):
+        from typing import Unpack
+
+        # typing_extensions.Unpack != typing.Unpack for 3.11, but we assume
+        # that typing_extensions.Unpack should not be used in that case
+        return typing.get_origin(obj) is Unpack
+
+    # 3.9 and 3.10 require typing_extensions.Unpack
+    origin = typing.get_origin(obj)
+    return (
+        getattr(origin, '__module__', None) == 'typing_extensions'
+        and _typing_internal_name(origin) == 'Unpack'
+    )
+
+
+def _typing_internal_name(obj: Any) -> str | None:
+    if sys.version_info[:2] >= (3, 10):
+        return obj.__name__
+    return getattr(obj, '_name', None)
+
+
+def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> str:
+    """Convert a type-like object to a reST reference.
 
     :param mode: Specify a method how annotations will be stringified.
 
@@ -161,31 +230,53 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
     from sphinx.ext.autodoc.mock import ismock, ismockmodule  # lazy loading
     from sphinx.util import inspect  # lazy loading
 
-    if mode == 'smart':
-        modprefix = '~'
-    else:
-        modprefix = ''
+    valid_modes = {'fully-qualified-except-typing', 'smart'}
+    if mode not in valid_modes:
+        valid = ', '.join(map(repr, sorted(valid_modes)))
+        msg = f'mode must be one of {valid}; got {mode!r}'
+        raise ValueError(msg)
+
+    # things that are not types
+    if cls in {None, NoneType}:
+        return ':py:obj:`None`'
+    if cls is Ellipsis:
+        return '...'
+    if isinstance(cls, str):
+        return cls
+
+    cls_module_is_typing = getattr(cls, '__module__', '') == 'typing'
+
+    # If the mode is 'smart', we always use '~'.
+    # If the mode is 'fully-qualified-except-typing',
+    # we use '~' only for the objects in the ``typing`` module.
+    module_prefix = '~' if mode == 'smart' or cls_module_is_typing else ''
 
     try:
-        if cls is None or cls is NoneType:
-            return ':py:obj:`None`'
-        elif cls is Ellipsis:
-            return '...'
-        elif isinstance(cls, str):
-            return cls
-        elif ismockmodule(cls):
-            return f':py:class:`{modprefix}{cls.__name__}`'
+        if ismockmodule(cls):
+            return f':py:class:`{module_prefix}{cls.__name__}`'
         elif ismock(cls):
-            return f':py:class:`{modprefix}{cls.__module__}.{cls.__name__}`'
+            return f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'
         elif is_invalid_builtin_class(cls):
-            return f':py:class:`{modprefix}{_INVALID_BUILTIN_CLASSES[cls]}`'
+            # The above predicate never raises TypeError but should not be
+            # evaluated before determining whether *cls* is a mocked object
+            # or not; instead of two try-except blocks, we keep it here.
+            return f':py:class:`{module_prefix}{_INVALID_BUILTIN_CLASSES[cls]}`'
+        elif _is_annotated_form(cls):
+            args = restify(cls.__args__[0], mode)
+            meta = ', '.join(map(repr, cls.__metadata__))
+            if sys.version_info[:2] <= (3, 11):
+                # Hardcoded to fix errors on Python 3.11 and earlier.
+                return fr':py:class:`~typing.Annotated`\ [{args}, {meta}]'
+            return (f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'
+                    fr'\ [{args}, {meta}]')
         elif inspect.isNewType(cls):
             if sys.version_info[:2] >= (3, 10):
                 # newtypes have correct module info since Python 3.10+
-                return f':py:class:`{modprefix}{cls.__module__}.{cls.__name__}`'
-            else:
-                return f':py:class:`{cls.__name__}`'
+                return f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'
+            return f':py:class:`{cls.__name__}`'
         elif UnionType and isinstance(cls, UnionType):
+            # Union types (PEP 585) retain their definition order when they
+            # are printed natively and ``None``-like types are kept as is.
             return ' | '.join(restify(a, mode) for a in cls.__args__)
         elif cls.__module__ in ('__builtin__', 'builtins'):
             if hasattr(cls, '__args__'):
@@ -194,73 +285,85 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
 
                 concatenated_args = ', '.join(restify(arg, mode) for arg in cls.__args__)
                 return fr':py:class:`{cls.__name__}`\ [{concatenated_args}]'
-            else:
-                return f':py:class:`{cls.__name__}`'
+            return f':py:class:`{cls.__name__}`'
         elif (inspect.isgenericalias(cls)
-              and cls.__module__ == 'typing'
-              and cls.__origin__ is Union):  # type: ignore[attr-defined]
-            return ' | '.join(restify(a, mode) for a in cls.__args__)  # type: ignore[attr-defined]
+              and cls_module_is_typing
+              and cls.__origin__ is Union):
+            # *cls* is defined in ``typing``, and thus ``__args__`` must exist
+            return ' | '.join(restify(a, mode) for a in cls.__args__)
         elif inspect.isgenericalias(cls):
-            if isinstance(cls.__origin__, typing._SpecialForm):  # type: ignore[attr-defined]
-                text = restify(cls.__origin__, mode)  # type: ignore[attr-defined,arg-type]
-            elif getattr(cls, '_name', None):
-                cls_name = cls._name  # type: ignore[attr-defined]
-                if cls.__module__ == 'typing':
-                    text = f':py:class:`~{cls.__module__}.{cls_name}`'
-                else:
-                    text = f':py:class:`{modprefix}{cls.__module__}.{cls_name}`'
+            # A generic alias always has an __origin__, but it is difficult to
+            # use a type guard on inspect.isgenericalias()
+            # (ideally, we would use ``TypeIs`` introduced in Python 3.13).
+            cls_name = _typing_internal_name(cls)
+
+            if isinstance(cls.__origin__, typing._SpecialForm):
+                # ClassVar; Concatenate; Final; Literal; Unpack; TypeGuard; TypeIs
+                # Required/NotRequired
+                text = restify(cls.__origin__, mode)
+            elif cls_name:
+                text = f':py:class:`{module_prefix}{cls.__module__}.{cls_name}`'
             else:
-                text = restify(cls.__origin__, mode)  # type: ignore[attr-defined]
-
-            origin = getattr(cls, '__origin__', None)
-            if not hasattr(cls, '__args__'):  # NoQA: SIM114
-                pass
-            elif all(is_system_TypeVar(a) for a in cls.__args__):
-                # Suppress arguments if all system defined TypeVars (ex. Dict[KT, VT])
-                pass
-            elif (cls.__module__ == 'typing'
-                  and cls._name == 'Callable'):  # type: ignore[attr-defined]
-                args = ', '.join(restify(a, mode) for a in cls.__args__[:-1])
-                text += fr"\ [[{args}], {restify(cls.__args__[-1], mode)}]"
-            elif cls.__module__ == 'typing' and getattr(origin, '_name', None) == 'Literal':
-                literal_args = []
-                for a in cls.__args__:
-                    if inspect.isenumattribute(a):
-                        literal_args.append(_format_literal_enum_arg(a, mode=mode))
-                    else:
-                        literal_args.append(repr(a))
-                text += fr"\ [{', '.join(literal_args)}]"
-                del literal_args
-            elif cls.__args__:
-                text += fr"\ [{', '.join(restify(a, mode) for a in cls.__args__)}]"
-
-            return text
+                text = restify(cls.__origin__, mode)
+
+            __args__ = getattr(cls, '__args__', ())
+            if not __args__:
+                return text
+            if all(map(is_system_TypeVar, __args__)):
+                # Don't print the arguments; they're all system defined type variables.
+                return text
+
+            # Callable has special formatting
+            if (
+                (cls_module_is_typing and _typing_internal_name(cls) == 'Callable')
+                or (cls.__module__ == 'collections.abc' and cls.__name__ == 'Callable')
+            ):
+                args = ', '.join(restify(a, mode) for a in __args__[:-1])
+                returns = restify(__args__[-1], mode)
+                return fr'{text}\ [[{args}], {returns}]'
+
+            if cls_module_is_typing and _typing_internal_name(cls.__origin__) == 'Literal':
+                args = ', '.join(_format_literal_arg_restify(a, mode=mode)
+                                 for a in cls.__args__)
+                return fr'{text}\ [{args}]'
+
+            # generic representation of the parameters
+            args = ', '.join(restify(a, mode) for a in __args__)
+            return fr'{text}\ [{args}]'
         elif isinstance(cls, typing._SpecialForm):
-            return f':py:obj:`~{cls.__module__}.{cls._name}`'
+            cls_name = _typing_internal_name(cls)
+            return f':py:obj:`~{cls.__module__}.{cls_name}`'
         elif sys.version_info[:2] >= (3, 11) and cls is typing.Any:
             # handle bpo-46998
             return f':py:obj:`~{cls.__module__}.{cls.__name__}`'
         elif hasattr(cls, '__qualname__'):
-            if cls.__module__ == 'typing':
-                return f':py:class:`~{cls.__module__}.{cls.__qualname__}`'
-            else:
-                return f':py:class:`{modprefix}{cls.__module__}.{cls.__qualname__}`'
+            return f':py:class:`{module_prefix}{cls.__module__}.{cls.__qualname__}`'
         elif isinstance(cls, ForwardRef):
             return f':py:class:`{cls.__forward_arg__}`'
         else:
-            # not a class (ex. TypeVar)
-            if cls.__module__ == 'typing':
-                return f':py:obj:`~{cls.__module__}.{cls.__name__}`'
-            else:
-                return f':py:obj:`{modprefix}{cls.__module__}.{cls.__name__}`'
+            # not a class (ex. TypeVar) but should have a __name__
+            return f':py:obj:`{module_prefix}{cls.__module__}.{cls.__name__}`'
     except (AttributeError, TypeError):
         return inspect.object_description(cls)
 
 
+def _format_literal_arg_restify(arg: Any, /, *, mode: str) -> str:
+    from sphinx.util.inspect import isenumattribute  # lazy loading
+
+    if isenumattribute(arg):
+        enum_cls = arg.__class__
+        if mode == 'smart' or enum_cls.__module__ == 'typing':
+            # MyEnum.member
+            return f':py:attr:`~{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+        # module.MyEnum.member
+        return f':py:attr:`{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+    return repr(arg)
+
+
 def stringify_annotation(
     annotation: Any,
     /,
-    mode: str = 'fully-qualified-except-typing',
+    mode: _StringifyMode = 'fully-qualified-except-typing',
 ) -> str:
     """Stringify type annotation object.
 
@@ -278,69 +381,76 @@ def stringify_annotation(
     from sphinx.ext.autodoc.mock import ismock, ismockmodule  # lazy loading
     from sphinx.util.inspect import isNewType  # lazy loading
 
-    if mode not in {'fully-qualified-except-typing', 'fully-qualified', 'smart'}:
-        msg = ("'mode' must be one of 'fully-qualified-except-typing', "
-               f"'fully-qualified', or 'smart'; got {mode!r}.")
+    valid_modes = {'fully-qualified-except-typing', 'fully-qualified', 'smart'}
+    if mode not in valid_modes:
+        valid = ', '.join(map(repr, sorted(valid_modes)))
+        msg = f'mode must be one of {valid}; got {mode!r}'
         raise ValueError(msg)
 
-    if mode == 'smart':
-        module_prefix = '~'
-    else:
-        module_prefix = ''
-
-    annotation_qualname = getattr(annotation, '__qualname__', '')
-    annotation_module = getattr(annotation, '__module__', '')
-    annotation_name = getattr(annotation, '__name__', '')
-    annotation_module_is_typing = annotation_module == 'typing'
-
+    # things that are not types
+    if annotation in {None, NoneType}:
+        return 'None'
+    if annotation is Ellipsis:
+        return '...'
     if isinstance(annotation, str):
         if annotation.startswith("'") and annotation.endswith("'"):
-            # might be a double Forward-ref'ed type.  Go unquoting.
+            # Might be a double Forward-ref'ed type.  Go unquoting.
             return annotation[1:-1]
-        else:
-            return annotation
-    elif isinstance(annotation, TypeVar):
+        return annotation
+    if not annotation:
+        return repr(annotation)
+
+    module_prefix = '~' if mode == 'smart' else ''
+
+    # The values below must be strings if the objects are well-formed.
+    annotation_qualname: str = getattr(annotation, '__qualname__', '')
+    annotation_module: str = getattr(annotation, '__module__', '')
+    annotation_name: str = getattr(annotation, '__name__', '')
+    annotation_module_is_typing = annotation_module == 'typing'
+
+    # Extract the annotation's base type by considering formattable cases
+    if isinstance(annotation, TypeVar) and not _is_unpack_form(annotation):
+        # typing_extensions.Unpack is incorrectly determined as a TypeVar
         if annotation_module_is_typing and mode in {'fully-qualified-except-typing', 'smart'}:
             return annotation_name
-        else:
-            return module_prefix + f'{annotation_module}.{annotation_name}'
+        return module_prefix + f'{annotation_module}.{annotation_name}'
     elif isNewType(annotation):
         if sys.version_info[:2] >= (3, 10):
             # newtypes have correct module info since Python 3.10+
             return module_prefix + f'{annotation_module}.{annotation_name}'
-        else:
-            return annotation_name
-    elif not annotation:
-        return repr(annotation)
-    elif annotation is NoneType:
-        return 'None'
+        return annotation_name
     elif ismockmodule(annotation):
         return module_prefix + annotation_name
     elif ismock(annotation):
         return module_prefix + f'{annotation_module}.{annotation_name}'
     elif is_invalid_builtin_class(annotation):
         return module_prefix + _INVALID_BUILTIN_CLASSES[annotation]
-    elif str(annotation).startswith('typing.Annotated'):  # for py310+
+    elif _is_annotated_form(annotation):  # for py39+
         pass
     elif annotation_module == 'builtins' and annotation_qualname:
-        if (args := getattr(annotation, '__args__', None)) is not None:  # PEP 585 generic
-            if not args:  # Empty tuple, list, ...
-                return repr(annotation)
-
-            concatenated_args = ', '.join(stringify_annotation(arg, mode) for arg in args)
-            return f'{annotation_qualname}[{concatenated_args}]'
-        else:
+        args = getattr(annotation, '__args__', None)
+        if args is None:
             return annotation_qualname
-    elif annotation is Ellipsis:
-        return '...'
+
+        # PEP 585 generic
+        if not args:  # Empty tuple, list, ...
+            return repr(annotation)
+
+        concatenated_args = ', '.join(stringify_annotation(arg, mode) for arg in args)
+        return f'{annotation_qualname}[{concatenated_args}]'
+    else:
+        # add other special cases that can be directly formatted
+        pass
 
     module_prefix = f'{annotation_module}.'
-    annotation_forward_arg = getattr(annotation, '__forward_arg__', None)
+    annotation_forward_arg: str | None = getattr(annotation, '__forward_arg__', None)
     if annotation_qualname or (annotation_module_is_typing and not annotation_forward_arg):
         if mode == 'smart':
-            module_prefix = '~' + module_prefix
+            module_prefix = f'~{module_prefix}'
         if annotation_module_is_typing and mode == 'fully-qualified-except-typing':
             module_prefix = ''
+    elif _is_unpack_form(annotation) and annotation_module == 'typing_extensions':
+        module_prefix = '~' if mode == 'smart' else ''
     else:
         module_prefix = ''
 
@@ -349,12 +459,13 @@ def stringify_annotation(
             # handle ForwardRefs
             qualname = annotation_forward_arg
         else:
-            _name = getattr(annotation, '_name', '')
-            if _name:
-                qualname = _name
+            if internal_name := _typing_internal_name(annotation):
+                qualname = internal_name
             elif annotation_qualname:
                 qualname = annotation_qualname
             else:
+                # in this case, we know that the annotation is a member
+                # of ``typing`` and all of them define ``__origin__``
                 qualname = stringify_annotation(
                     annotation.__origin__, 'fully-qualified-except-typing',
                 ).replace('typing.', '')  # ex. Union
@@ -370,36 +481,38 @@ def stringify_annotation(
         # only make them appear twice
         return repr(annotation)
 
-    annotation_args = getattr(annotation, '__args__', None)
-    if annotation_args:
-        if not isinstance(annotation_args, (list, tuple)):
-            # broken __args__ found
-            pass
-        elif qualname in {'Optional', 'Union', 'types.UnionType'}:
+    # Process the generic arguments (if any).
+    # They must be a list or a tuple, otherwise they are considered 'broken'.
+    annotation_args = getattr(annotation, '__args__', ())
+    if annotation_args and isinstance(annotation_args, (list, tuple)):
+        if (
+            qualname in {'Union', 'types.UnionType'}
+            and all(getattr(a, '__origin__', ...) is typing.Literal for a in annotation_args)
+        ):
+            # special case to flatten a Union of Literals into a literal
+            flattened_args = typing.Literal[annotation_args].__args__  # type: ignore[attr-defined]
+            args = ', '.join(_format_literal_arg_stringify(a, mode=mode)
+                             for a in flattened_args)
+            return f'{module_prefix}Literal[{args}]'
+        if qualname in {'Optional', 'Union', 'types.UnionType'}:
             return ' | '.join(stringify_annotation(a, mode) for a in annotation_args)
         elif qualname == 'Callable':
             args = ', '.join(stringify_annotation(a, mode) for a in annotation_args[:-1])
             returns = stringify_annotation(annotation_args[-1], mode)
             return f'{module_prefix}Callable[[{args}], {returns}]'
         elif qualname == 'Literal':
-            from sphinx.util.inspect import isenumattribute  # lazy loading
-
-            def format_literal_arg(arg: Any) -> str:
-                if isenumattribute(arg):
-                    enumcls = arg.__class__
-
-                    if mode == 'smart':
-                        # MyEnum.member
-                        return f'{enumcls.__qualname__}.{arg.name}'
-
-                    # module.MyEnum.member
-                    return f'{enumcls.__module__}.{enumcls.__qualname__}.{arg.name}'
-                return repr(arg)
-
-            args = ', '.join(map(format_literal_arg, annotation_args))
+            args = ', '.join(_format_literal_arg_stringify(a, mode=mode)
+                             for a in annotation_args)
             return f'{module_prefix}Literal[{args}]'
-        elif str(annotation).startswith('typing.Annotated'):  # for py39+
-            return stringify_annotation(annotation_args[0], mode)
+        elif _is_annotated_form(annotation):  # for py39+
+            args = stringify_annotation(annotation_args[0], mode)
+            meta = ', '.join(map(repr, annotation.__metadata__))
+            if sys.version_info[:2] <= (3, 11):
+                if mode == 'fully-qualified-except-typing':
+                    return f'Annotated[{args}, {meta}]'
+                module_prefix = module_prefix.replace('builtins', 'typing')
+                return f'{module_prefix}Annotated[{args}, {meta}]'
+            return f'{module_prefix}Annotated[{args}, {meta}]'
         elif all(is_system_TypeVar(a) for a in annotation_args):
             # Suppress arguments if all system defined TypeVars (ex. Dict[KT, VT])
             return module_prefix + qualname
@@ -410,12 +523,17 @@ def stringify_annotation(
     return module_prefix + qualname
 
 
-def _format_literal_enum_arg(arg: enum.Enum, /, *, mode: str) -> str:
-    enum_cls = arg.__class__
-    if mode == 'smart' or enum_cls.__module__ == 'typing':
-        return f':py:attr:`~{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
-    else:
-        return f':py:attr:`{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+def _format_literal_arg_stringify(arg: Any, /, *, mode: str) -> str:
+    from sphinx.util.inspect import isenumattribute  # lazy loading
+
+    if isenumattribute(arg):
+        enum_cls = arg.__class__
+        if mode == 'smart' or enum_cls.__module__ == 'typing':
+            # MyEnum.member
+            return f'{enum_cls.__qualname__}.{arg.name}'
+        # module.MyEnum.member
+        return f'{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}'
+    return repr(arg)
 
 
 # deprecated name -> (object to return, canonical path or empty string, removal version)

sphinx/versioning.py

@@ -12,7 +12,7 @@ from uuid import uuid4
 from sphinx.transforms import SphinxTransform
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
     from docutils.nodes import Node
 
@@ -30,7 +30,7 @@ except ImportError:
 VERSIONING_RATIO = 65
 
 
-def add_uids(doctree: Node, condition: Any) -> Iterator[Node]:
+def add_uids(doctree: Node, condition: Callable[[Node], bool]) -> Iterator[Node]:
     """Add a unique id to every node in the `doctree` which matches the
     condition and yield the nodes.
 
@@ -41,11 +41,11 @@ def add_uids(doctree: Node, condition: Any) -> Iterator[Node]:
         A callable which returns either ``True`` or ``False`` for a given node.
     """
     for node in doctree.findall(condition):
-        node.uid = uuid4().hex
+        node.uid = uuid4().hex  # type: ignore[attr-defined]
         yield node
 
 
-def merge_doctrees(old: Node, new: Node, condition: Any) -> Iterator[Node]:
+def merge_doctrees(old: Node, new: Node, condition: Callable[[Node], bool]) -> Iterator[Node]:
     """Merge the `old` doctree with the `new` one while looking at nodes
     matching the `condition`.
 
@@ -68,13 +68,13 @@ def merge_doctrees(old: Node, new: Node, condition: Any) -> Iterator[Node]:
             continue
         if not getattr(old_node, 'uid', None):
             # maybe config.gettext_uuid has been changed.
-            old_node.uid = uuid4().hex
+            old_node.uid = uuid4().hex  # type: ignore[union-attr]
         if new_node is None:
             old_nodes.append(old_node)
             continue
-        ratio = get_ratio(old_node.rawsource, new_node.rawsource)
+        ratio = get_ratio(old_node.rawsource, new_node.rawsource)  # type: ignore[union-attr]
         if ratio == 0:
-            new_node.uid = old_node.uid
+            new_node.uid = old_node.uid  # type: ignore[union-attr]
             seen.add(new_node)
         else:
             ratios[old_node, new_node] = ratio
@@ -85,30 +85,29 @@ def merge_doctrees(old: Node, new: Node, condition: Any) -> Iterator[Node]:
     for old_node, new_node in product(old_nodes, new_nodes):
         if new_node in seen or (old_node, new_node) in ratios:
             continue
-        ratio = get_ratio(old_node.rawsource, new_node.rawsource)
+        ratio = get_ratio(old_node.rawsource, new_node.rawsource)  # type: ignore[union-attr]
         if ratio == 0:
-            new_node.uid = old_node.uid
+            new_node.uid = old_node.uid  # type: ignore[union-attr]
             seen.add(new_node)
         else:
             ratios[old_node, new_node] = ratio
     # choose the old node with the best ratio for each new node and set the uid
     # as long as the ratio is under a certain value, in which case we consider
     # them not changed but different
-    ratios = sorted(ratios.items(), key=itemgetter(1))  # type: ignore[assignment]
-    for (old_node, new_node), ratio in ratios:
+    for (old_node, new_node), ratio in sorted(ratios.items(), key=itemgetter(1)):
         if new_node in seen:
             continue
         else:
             seen.add(new_node)
         if ratio < VERSIONING_RATIO:
-            new_node.uid = old_node.uid
+            new_node.uid = old_node.uid  # type: ignore[union-attr]
         else:
-            new_node.uid = uuid4().hex
+            new_node.uid = uuid4().hex  # type: ignore[union-attr]
             yield new_node
     # create new uuids for any new node we left out earlier, this happens
     # if one or more nodes are simply added.
     for new_node in set(new_nodes) - seen:
-        new_node.uid = uuid4().hex
+        new_node.uid = uuid4().hex  # type: ignore[union-attr]
         yield new_node
 
 
@@ -153,7 +152,8 @@ class UIDTransform(SphinxTransform):
     def apply(self, **kwargs: Any) -> None:
         env = self.env
         old_doctree = None
-        if not env.versioning_condition:
+        versioning_condition = env.versioning_condition
+        if not versioning_condition:
             return
 
         if env.versioning_compare:
@@ -167,9 +167,9 @@ class UIDTransform(SphinxTransform):
 
         # add uids for versioning
         if not env.versioning_compare or old_doctree is None:
-            list(add_uids(self.document, env.versioning_condition))
+            list(add_uids(self.document, versioning_condition))
         else:
-            list(merge_doctrees(old_doctree, self.document, env.versioning_condition))
+            list(merge_doctrees(old_doctree, self.document, versioning_condition))
 
 
 def setup(app: Sphinx) -> ExtensionMetadata: