Sphinx 7.4.7__py3-none-any.whl → 8.0.0rc1__py3-none-any.whl

sphinx/util/typing.py

@@ -6,15 +6,15 @@ import dataclasses
 import sys
 import types
 import typing
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from contextvars import Context, ContextVar, Token
 from struct import Struct
 from typing import (
     TYPE_CHECKING,
     Annotated,
     Any,
-    Callable,
     ForwardRef,
+    NewType,
     TypedDict,
     TypeVar,
     Union,
@@ -25,9 +25,9 @@ from docutils.parsers.rst.states import Inliner
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
-    from typing import Final, Literal, Protocol
+    from typing import Final, Literal, Protocol, TypeAlias
 
-    from typing_extensions import TypeAlias, TypeIs
+    from typing_extensions import TypeIs
 
     from sphinx.application import Sphinx
 
@@ -41,10 +41,6 @@ if TYPE_CHECKING:
         'smart',
     ]
 
-if sys.version_info >= (3, 10):
-    from types import UnionType
-else:
-    UnionType = None
 
 # classes that have an incorrect .__module__ attribute
 _INVALID_BUILTIN_CLASSES: Final[Mapping[object, str]] = {
@@ -85,13 +81,10 @@ def is_invalid_builtin_class(obj: Any) -> bool:
 
 
 # Text like nodes which are initialized with text and rawsource
-TextlikeNode = Union[nodes.Text, nodes.TextElement]
-
-# type of None
-NoneType = type(None)
+TextlikeNode: TypeAlias = nodes.Text | nodes.TextElement
 
 # path matcher
-PathMatcher = Callable[[str], bool]
+PathMatcher: TypeAlias = Callable[[str], bool]
 
 # common role functions
 if TYPE_CHECKING:
@@ -109,25 +102,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
 ]
-Inventory = dict[str, dict[str, InventoryItem]]
+Inventory: TypeAlias = dict[str, dict[str, InventoryItem]]
 
 
 class ExtensionMetadata(TypedDict, total=False):
@@ -151,7 +144,7 @@ class ExtensionMetadata(TypedDict, total=False):
 
 
 if TYPE_CHECKING:
-    _ExtensionSetupFunc = Callable[[Sphinx], ExtensionMetadata]
+    _ExtensionSetupFunc: TypeAlias = Callable[[Sphinx], ExtensionMetadata]
 
 
 def get_type_hints(
@@ -204,24 +197,14 @@ def _is_unpack_form(obj: Any) -> bool:
         # 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
+    # Python 3.10 requires typing_extensions.Unpack
     origin = typing.get_origin(obj)
     return (
         getattr(origin, '__module__', None) == 'typing_extensions'
-        and _typing_internal_name(origin) == 'Unpack'
+        and origin.__name__ == 'Unpack'
     )
 
 
-def _typing_internal_name(obj: Any) -> str | None:
-    if sys.version_info[:2] >= (3, 10):
-        try:
-            return obj.__name__
-        except AttributeError:
-            # e.g. ParamSpecArgs, ParamSpecKwargs
-            return ''
-    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.
 
@@ -234,7 +217,7 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
                      Show the name of the annotation.
     """
     from sphinx.ext.autodoc.mock import ismock, ismockmodule  # lazy loading
-    from sphinx.util import inspect  # lazy loading
+    from sphinx.util.inspect import isgenericalias, object_description  # lazy loading
 
     valid_modes = {'fully-qualified-except-typing', 'smart'}
     if mode not in valid_modes:
@@ -243,7 +226,7 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
         raise ValueError(msg)
 
     # things that are not types
-    if cls is None or cls == NoneType:
+    if cls is None or cls == types.NoneType:
         return ':py:obj:`None`'
     if cls is Ellipsis:
         return '...'
@@ -288,12 +271,9 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
                 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:`{module_prefix}{cls.__module__}.{cls.__name__}`'
-            return f':py:class:`{cls.__name__}`'
-        elif UnionType and isinstance(cls, UnionType):
+        elif isinstance(cls, NewType):
+            return f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'  # type: ignore[attr-defined]
+        elif isinstance(cls, types.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__)
@@ -305,23 +285,18 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
                 concatenated_args = ', '.join(restify(arg, mode) for arg in cls.__args__)
                 return fr':py:class:`{cls.__name__}`\ [{concatenated_args}]'
             return f':py:class:`{cls.__name__}`'
-        elif (inspect.isgenericalias(cls)
+        elif (isgenericalias(cls)
               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):
-            # 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)
-
+        elif isgenericalias(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}`'
+            elif cls.__name__:
+                text = f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'
             else:
                 text = restify(cls.__origin__, mode)
 
@@ -334,14 +309,14 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
 
             # Callable has special formatting
             if (
-                (cls_module_is_typing and _typing_internal_name(cls) == 'Callable')
+                (cls_module_is_typing and cls.__name__ == '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':
+            if cls_module_is_typing and cls.__origin__.__name__ == 'Literal':
                 args = ', '.join(_format_literal_arg_restify(a, mode=mode)
                                  for a in cls.__args__)
                 return fr'{text}\ [{args}]'
@@ -350,8 +325,7 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
             args = ', '.join(restify(a, mode) for a in __args__)
             return fr'{text}\ [{args}]'
         elif isinstance(cls, typing._SpecialForm):
-            cls_name = _typing_internal_name(cls)
-            return f':py:obj:`~{cls.__module__}.{cls_name}`'
+            return f':py:obj:`~{cls.__module__}.{cls.__name__}`'  # type: ignore[attr-defined]
         elif sys.version_info[:2] >= (3, 11) and cls is typing.Any:
             # handle bpo-46998
             return f':py:obj:`~{cls.__module__}.{cls.__name__}`'
@@ -363,7 +337,7 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
             # 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)
+        return object_description(cls)
 
 
 def _format_literal_arg_restify(arg: Any, /, *, mode: str) -> str:
@@ -398,7 +372,6 @@ def stringify_annotation(
                      Show the module name and qualified name of the annotation.
     """
     from sphinx.ext.autodoc.mock import ismock, ismockmodule  # lazy loading
-    from sphinx.util.inspect import isNewType  # lazy loading
 
     valid_modes = {'fully-qualified-except-typing', 'fully-qualified', 'smart'}
     if mode not in valid_modes:
@@ -407,7 +380,7 @@ def stringify_annotation(
         raise ValueError(msg)
 
     # things that are not types
-    if annotation is None or annotation == NoneType:
+    if annotation is None or annotation == types.NoneType:
         return 'None'
     if annotation is Ellipsis:
         return '...'
@@ -433,18 +406,15 @@ def stringify_annotation(
         if annotation_module_is_typing and mode in {'fully-qualified-except-typing', 'smart'}:
             return 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}'
-        return annotation_name
+    elif isinstance(annotation, NewType):
+        return module_prefix + f'{annotation_module}.{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 _is_annotated_form(annotation):  # for py39+
+    elif _is_annotated_form(annotation):  # for py310+
         pass
     elif annotation_module == 'builtins' and annotation_qualname:
         args = getattr(annotation, '__args__', None)
@@ -478,8 +448,8 @@ def stringify_annotation(
             # handle ForwardRefs
             qualname = annotation_forward_arg
         else:
-            if internal_name := _typing_internal_name(annotation):
-                qualname = internal_name
+            if annotation_name:
+                qualname = annotation_name
             elif annotation_qualname:
                 qualname = annotation_qualname
             else:
@@ -493,7 +463,7 @@ def stringify_annotation(
     elif hasattr(annotation, '__origin__'):
         # instantiated generic provided by a user
         qualname = stringify_annotation(annotation.__origin__, mode)
-    elif UnionType and isinstance(annotation, UnionType):  # types.UnionType (for py3.10+)
+    elif isinstance(annotation, types.UnionType):
         qualname = 'types.UnionType'
     else:
         # we weren't able to extract the base type, appending arguments would
@@ -503,7 +473,7 @@ def stringify_annotation(
     # 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 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)
@@ -523,7 +493,7 @@ def stringify_annotation(
             args = ', '.join(_format_literal_arg_stringify(a, mode=mode)
                              for a in annotation_args)
             return f'{module_prefix}Literal[{args}]'
-        elif _is_annotated_form(annotation):  # for py39+
+        elif _is_annotated_form(annotation):  # for py310+
             args = stringify_annotation(annotation_args[0], mode)
             meta_args = []
             for m in annotation.__metadata__:
@@ -539,11 +509,6 @@ def stringify_annotation(
                 else:
                     meta_args.append(repr(m))
             meta = ', '.join(meta_args)
-            if sys.version_info[:2] <= (3, 9):
-                if mode == 'smart':
-                    return f'~typing.Annotated[{args}, {meta}]'
-                if mode == 'fully-qualified':
-                    return f'typing.Annotated[{args}, {meta}]'
             if sys.version_info[:2] <= (3, 11):
                 if mode == 'fully-qualified-except-typing':
                     return f'Annotated[{args}, {meta}]'
@@ -575,7 +540,6 @@ def _format_literal_arg_stringify(arg: Any, /, *, mode: str) -> str:
 
 # deprecated name -> (object to return, canonical path or empty string, removal version)
 _DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
-    'stringify': (stringify_annotation, 'sphinx.util.typing.stringify_annotation', (8, 0)),
 }
 
 

sphinx/writers/html.py

@@ -20,7 +20,7 @@ HTMLTranslator = HTML5Translator
 # https://www.arnebrodowski.de/blog/write-your-own-restructuredtext-writer.html
 
 
-class HTMLWriter(Writer):
+class HTMLWriter(Writer):  # type: ignore[misc]
 
     # override embed-stylesheet default value to False.
     settings_default_overrides = {"embed_stylesheet": False}

sphinx/writers/html5.py

@@ -43,7 +43,7 @@ def multiply_length(length: str, scale: int) -> str:
     return f"{int(result)}{unit}"
 
 
-class HTML5Translator(SphinxTranslator, BaseTranslator):
+class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
     """
     Our custom HTML translator.
     """

sphinx/writers/latex.py

@@ -66,7 +66,7 @@ class UnsupportedError(SphinxError):
     category = 'Markup is unsupported in LaTeX'
 
 
-class LaTeXWriter(writers.Writer):
+class LaTeXWriter(writers.Writer):  # type: ignore[misc]
 
     supported = ('sphinxlatex',)
 
@@ -1369,7 +1369,7 @@ class LaTeXTranslator(SphinxTranslator):
                 not isinstance(node.parent[index - 1], nodes.compound)):
             # insert blank line, if the paragraph follows a non-paragraph node in a compound
             self.body.append(r'\noindent' + CR)
-        elif index == 1 and isinstance(node.parent, (nodes.footnote, footnotetext)):
+        elif index == 1 and isinstance(node.parent, nodes.footnote | footnotetext):
             # don't insert blank line, if the paragraph is second child of a footnote
             # (first one is label node)
             pass
@@ -2081,7 +2081,7 @@ class LaTeXTranslator(SphinxTranslator):
         done = 0
         if len(node.children) == 1:
             child = node.children[0]
-            if isinstance(child, (nodes.bullet_list, nodes.enumerated_list)):
+            if isinstance(child, nodes.bullet_list | nodes.enumerated_list):
                 done = 1
         if not done:
             self.body.append(r'\begin{quote}' + CR)
@@ -2092,7 +2092,7 @@ class LaTeXTranslator(SphinxTranslator):
         done = 0
         if len(node.children) == 1:
             child = node.children[0]
-            if isinstance(child, (nodes.bullet_list, nodes.enumerated_list)):
+            if isinstance(child, nodes.bullet_list | nodes.enumerated_list):
                 done = 1
         if not done:
             self.body.append(r'\end{quote}' + CR)

sphinx/writers/manpage.py

@@ -24,7 +24,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class ManualPageWriter(Writer):
+class ManualPageWriter(Writer):  # type: ignore[misc]
     def __init__(self, builder: Builder) -> None:
         super().__init__()
         self.builder = builder
@@ -70,7 +70,7 @@ class NestedInlineTransform:
                     node.parent.remove(node)
 
 
-class ManualPageTranslator(SphinxTranslator, BaseTranslator):
+class ManualPageTranslator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
     """
     Custom man page translator.
     """

sphinx/writers/texinfo.py

@@ -105,7 +105,7 @@ def smart_capwords(s: str, sep: str | None = None) -> str:
     return (sep or ' ').join(words)
 
 
-class TexinfoWriter(writers.Writer):
+class TexinfoWriter(writers.Writer):  # type: ignore[misc]
     """Texinfo writer for generating Texinfo documents."""
 
     supported = ('texinfo', 'texi')
@@ -297,7 +297,7 @@ class TexinfoTranslator(SphinxTranslator):
         # try to find a suitable "Top" node
         title = self.document.next_node(nodes.title)
         top = title.parent if title else self.document
-        if not isinstance(top, (nodes.document, nodes.section)):
+        if not isinstance(top, nodes.document | nodes.section):
             top = self.document
         if top is not self.document:
             entries = node_menus[top['node_name']]
@@ -625,7 +625,7 @@ class TexinfoTranslator(SphinxTranslator):
         parent = node.parent
         if isinstance(parent, nodes.table):
             return
-        if isinstance(parent, (nodes.Admonition, nodes.sidebar, nodes.topic)):
+        if isinstance(parent, nodes.Admonition | nodes.sidebar | nodes.topic):
             raise nodes.SkipNode
         if not isinstance(parent, nodes.section):
             logger.warning(__('encountered title node not in section, topic, table, '
@@ -694,7 +694,7 @@ class TexinfoTranslator(SphinxTranslator):
     def visit_reference(self, node: Element) -> None:
         # an xref's target is displayed in Info so we ignore a few
         # cases for the sake of appearance
-        if isinstance(node.parent, (nodes.title, addnodes.desc_type)):
+        if isinstance(node.parent, nodes.title | addnodes.desc_type):
             return
         if len(node) != 0 and isinstance(node[0], nodes.image):
             return
@@ -987,7 +987,7 @@ class TexinfoTranslator(SphinxTranslator):
             self.add_anchor(id, node)
         # anchors and indexes need to go in front
         for n in node[::]:
-            if isinstance(n, (addnodes.index, nodes.target)):
+            if isinstance(n, addnodes.index | nodes.target):
                 n.walkabout(self)
                 node.remove(n)
         self.body.append('\n%s ' % self.at_item_x)

sphinx/writers/text.py

@@ -6,7 +6,7 @@ import os
 import re
 import textwrap
 from collections.abc import Iterable, Iterator, Sequence
-from itertools import chain, groupby
+from itertools import chain, groupby, pairwise
 from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes, writers
@@ -221,10 +221,10 @@ class Table:
             tail = "+" if out[-1][0] == "-" else "|"
             glue = [
                 "+" if left[0] == "-" or right[0] == "-" else "|"
-                for left, right in zip(out, out[1:])
+                for left, right in pairwise(out)
             ]
             glue.append(tail)
-            return head + "".join(chain.from_iterable(zip(out, glue)))
+            return head + "".join(chain.from_iterable(zip(out, glue, strict=False)))
 
         for lineno, line in enumerate(self.lines):
             if self.separator and lineno == self.separator:
@@ -356,7 +356,7 @@ def my_wrap(text: str, width: int = MAXWIDTH, **kwargs: Any) -> list[str]:
     return w.wrap(text)
 
 
-class TextWriter(writers.Writer):
+class TextWriter(writers.Writer):  # type: ignore[misc]
     supported = ('text',)
     settings_spec = ('No options here.', '', ())
     settings_defaults: dict[str, Any] = {}

sphinx/writers/xml.py

@@ -10,7 +10,7 @@ if TYPE_CHECKING:
     from sphinx.builders import Builder
 
 
-class XMLWriter(BaseXMLWriter):
+class XMLWriter(BaseXMLWriter):  # type: ignore[misc]
     output: str
 
     def __init__(self, builder: Builder) -> None:
@@ -29,7 +29,7 @@ class XMLWriter(BaseXMLWriter):
         return super().translate()
 
 
-class PseudoXMLWriter(BaseXMLWriter):
+class PseudoXMLWriter(BaseXMLWriter):  # type: ignore[misc]
 
     supported = ('pprint', 'pformat', 'pseudoxml')
     """Formats this writer supports."""

{sphinx-7.4.7.dist-info → sphinx-8.0.0rc1.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
 Name: Sphinx
-Version: 7.4.7
+Version: 8.0.0rc1
 Summary: Python documentation generator
 Author-email: Georg Brandl <georg@python.org>
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
@@ -18,7 +18,6 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -57,17 +56,19 @@ Requires-Dist: alabaster~=0.7.14
 Requires-Dist: imagesize>=1.3
 Requires-Dist: requests>=2.30.0
 Requires-Dist: packaging>=23.0
-Requires-Dist: importlib-metadata>=6.0; python_version < '3.10'
 Requires-Dist: tomli>=2; python_version < '3.11'
 Requires-Dist: colorama>=0.4.6; sys_platform == 'win32'
 Requires-Dist: sphinxcontrib-websupport ; extra == "docs"
 Requires-Dist: flake8>=6.0 ; extra == "lint"
-Requires-Dist: ruff==0.5.2 ; extra == "lint"
-Requires-Dist: mypy==1.10.1 ; extra == "lint"
+Requires-Dist: ruff==0.5.4 ; extra == "lint"
+Requires-Dist: mypy==1.11.0 ; extra == "lint"
 Requires-Dist: sphinx-lint>=0.9 ; extra == "lint"
-Requires-Dist: types-docutils==0.21.0.20240711 ; extra == "lint"
+Requires-Dist: types-colorama==0.4.15.20240311 ; extra == "lint"
+Requires-Dist: types-defusedxml==0.7.0.20240218 ; extra == "lint"
+Requires-Dist: types-docutils==0.21.0.20240724 ; extra == "lint"
+Requires-Dist: types-Pillow==10.2.0.20240520 ; extra == "lint"
+Requires-Dist: types-Pygments==2.18.0.20240506 ; extra == "lint"
 Requires-Dist: types-requests>=2.30.0 ; extra == "lint"
-Requires-Dist: importlib-metadata>=6.0 ; extra == "lint"
 Requires-Dist: tomli>=2 ; extra == "lint"
 Requires-Dist: pytest>=6.0 ; extra == "lint"
 Requires-Dist: pytest>=8.0 ; extra == "test"
@@ -134,7 +135,7 @@ Installation
 The following command installs Sphinx from the `Python Package Index`_. You will
 need a working installation of Python and pip.
 
-.. code-block:: sh
+.. code-block:: shell
 
    pip install -U sphinx