Sphinx 7.2.6__py3-none-any.whl → 7.3.0__py3-none-any.whl

sphinx/ext/intersphinx.py

@@ -34,6 +34,7 @@ from docutils.utils import relative_path
 import sphinx
 from sphinx.addnodes import pending_xref
 from sphinx.builders.html import INVENTORY_FILENAME
+from sphinx.deprecation import _deprecation_warning
 from sphinx.errors import ExtensionError
 from sphinx.locale import _, __
 from sphinx.transforms.post_transforms import ReferencesResolver
@@ -53,7 +54,7 @@ if TYPE_CHECKING:
     from sphinx.config import Config
     from sphinx.domains import Domain
     from sphinx.environment import BuildEnvironment
-    from sphinx.util.typing import Inventory, InventoryItem, RoleFunction
+    from sphinx.util.typing import ExtensionMetadata, Inventory, InventoryItem, RoleFunction
 
     InventoryCacheEntry = tuple[Union[str, None], int, Inventory]
 
@@ -245,7 +246,7 @@ def fetch_inventory_group(
             for fail in failures:
                 logger.info(*fail)
         else:
-            issues = '\n'.join([f[0] % f[1:] for f in failures])
+            issues = '\n'.join(f[0] % f[1:] for f in failures)
             logger.warning(__("failed to reach any of the inventories "
                               "with the following issues:") + "\n" + issues)
 
@@ -334,8 +335,10 @@ def _resolve_reference_in_domain_by_target(
         if target in inventory[objtype]:
             # Case sensitive match, use it
             data = inventory[objtype][target]
-        elif objtype == 'std:term':
-            # Check for potential case insensitive matches for terms only
+        elif objtype in {'std:label', 'std:term'}:
+            # Some types require case insensitive matches:
+            # * 'term': https://github.com/sphinx-doc/sphinx/issues/9291
+            # * 'label': https://github.com/sphinx-doc/sphinx/issues/12008
             target_lower = target.lower()
             insensitive_matches = list(filter(lambda k: k.lower() == target_lower,
                                               inventory[objtype].keys()))
@@ -479,7 +482,6 @@ def resolve_reference_detect_inventory(env: BuildEnvironment,
     to form ``inv_name:newtarget``. If ``inv_name`` is a named inventory, then resolution
     is tried in that inventory with the new target.
     """
-
     # ordinary direct lookup, use data as is
     res = resolve_reference_any_inventory(env, True, node, contnode)
     if res is not None:
@@ -501,7 +503,6 @@ def resolve_reference_detect_inventory(env: BuildEnvironment,
 def missing_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref,
                       contnode: TextElement) -> nodes.reference | None:
     """Attempt to resolve a missing reference via intersphinx references."""
-
     return resolve_reference_detect_inventory(env, node, contnode)
 
 
@@ -533,17 +534,90 @@ class IntersphinxRole(SphinxRole):
         assert self.name == self.orig_name.lower()
         inventory, name_suffix = self.get_inventory_and_name_suffix(self.orig_name)
         if inventory and not inventory_exists(self.env, inventory):
-            logger.warning(__('inventory for external cross-reference not found: %s'),
-                           inventory, location=(self.env.docname, self.lineno))
+            self._emit_warning(
+                __('inventory for external cross-reference not found: %r'), inventory
+            )
             return [], []
 
-        role_name = self.get_role_name(name_suffix)
+        domain_name, role_name = self._get_domain_role(name_suffix)
+
         if role_name is None:
-            logger.warning(__('role for external cross-reference not found: %s'), name_suffix,
-                           location=(self.env.docname, self.lineno))
+            self._emit_warning(
+                __('invalid external cross-reference suffix: %r'), name_suffix
+            )
             return [], []
 
-        result, messages = self.invoke_role(role_name)
+        # attempt to find a matching role function
+        role_func: RoleFunction | None
+
+        if domain_name is not None:
+            # the user specified a domain, so we only check that
+            if (domain := self.env.domains.get(domain_name)) is None:
+                self._emit_warning(
+                    __('domain for external cross-reference not found: %r'), domain_name
+                )
+                return [], []
+            if (role_func := domain.roles.get(role_name)) is None:
+                msg = 'role for external cross-reference not found in domain %r: %r'
+                if (
+                    object_types := domain.object_types.get(role_name)
+                ) is not None and object_types.roles:
+                    self._emit_warning(
+                        __(f'{msg} (perhaps you meant one of: %s)'),
+                        domain_name,
+                        role_name,
+                        self._concat_strings(object_types.roles),
+                    )
+                else:
+                    self._emit_warning(__(msg), domain_name, role_name)
+                return [], []
+
+        else:
+            # the user did not specify a domain,
+            # so we check first the default (if available) then standard domains
+            domains: list[Domain] = []
+            if default_domain := self.env.temp_data.get('default_domain'):
+                domains.append(default_domain)
+            if (
+                std_domain := self.env.domains.get('std')
+            ) is not None and std_domain not in domains:
+                domains.append(std_domain)
+
+            role_func = None
+            for domain in domains:
+                if (role_func := domain.roles.get(role_name)) is not None:
+                    domain_name = domain.name
+                    break
+
+            if role_func is None or domain_name is None:
+                domains_str = self._concat_strings(d.name for d in domains)
+                msg = 'role for external cross-reference not found in domains %s: %r'
+                possible_roles: set[str] = set()
+                for d in domains:
+                    if o := d.object_types.get(role_name):
+                        possible_roles.update(f'{d.name}:{r}' for r in o.roles)
+                if possible_roles:
+                    msg = f'{msg} (perhaps you meant one of: %s)'
+                    self._emit_warning(
+                        __(msg),
+                        domains_str,
+                        role_name,
+                        self._concat_strings(possible_roles),
+                    )
+                else:
+                    self._emit_warning(__(msg), domains_str, role_name)
+                return [], []
+
+        result, messages = role_func(
+            f'{domain_name}:{role_name}',
+            self.rawtext,
+            self.text,
+            self.lineno,
+            self.inliner,
+            self.options,
+            self.content,
+        )
+
         for node in result:
             if isinstance(node, pending_xref):
                 node['intersphinx'] = True
@@ -552,13 +626,17 @@ class IntersphinxRole(SphinxRole):
         return result, messages
 
     def get_inventory_and_name_suffix(self, name: str) -> tuple[str | None, str]:
+        """Extract an inventory name (if any) and ``domain+name`` suffix from a role *name*.
+        and the domain+name suffix.
+
+        The role name is expected to be of one of the following forms:
+
+        - ``external+inv:name`` -- explicit inventory and name, any domain.
+        - ``external+inv:domain:name`` -- explicit inventory, domain and name.
+        - ``external:name`` -- any inventory and domain, explicit name.
+        - ``external:domain:name`` -- any inventory, explicit domain and name.
+        """
         assert name.startswith('external'), name
-        # either we have an explicit inventory name, i.e,
-        # :external+inv:role:        or
-        # :external+inv:domain:role:
-        # or we look in all inventories, i.e.,
-        # :external:role:            or
-        # :external:domain:role:
         suffix = name[9:]
         if name[8] == '+':
             inv_name, suffix = suffix.split(':', 1)
@@ -569,7 +647,39 @@ class IntersphinxRole(SphinxRole):
             msg = f'Malformed :external: role name: {name}'
             raise ValueError(msg)
 
+    def _get_domain_role(self, name: str) -> tuple[str | None, str | None]:
+        """Convert the *name* string into a domain and a role name.
+
+        - If *name* contains no ``:``, return ``(None, name)``.
+        - If *name* contains a single ``:``, the domain/role is split on this.
+        - If *name* contains multiple ``:``, return ``(None, None)``.
+        """
+        names = name.split(':')
+        if len(names) == 1:
+            return None, names[0]
+        elif len(names) == 2:
+            return names[0], names[1]
+        else:
+            return None, None
+
+    def _emit_warning(self, msg: str, /, *args: Any) -> None:
+        logger.warning(
+            msg,
+            *args,
+            type='intersphinx',
+            subtype='external',
+            location=(self.env.docname, self.lineno),
+        )
+
+    def _concat_strings(self, strings: Iterable[str]) -> str:
+        return ', '.join(f'{s!r}' for s in sorted(strings))
+
+    # deprecated methods
+
     def get_role_name(self, name: str) -> tuple[str, str] | None:
+        _deprecation_warning(
+            __name__, f'{self.__class__.__name__}.get_role_name', '', remove=(9, 0)
+        )
         names = name.split(':')
         if len(names) == 1:
             # role
@@ -591,6 +701,9 @@ class IntersphinxRole(SphinxRole):
             return None
 
     def is_existent_role(self, domain_name: str, role_name: str) -> bool:
+        _deprecation_warning(
+            __name__, f'{self.__class__.__name__}.is_existent_role', '', remove=(9, 0)
+        )
         try:
             domain = self.env.get_domain(domain_name)
             return role_name in domain.roles
@@ -598,6 +711,10 @@ class IntersphinxRole(SphinxRole):
             return False
 
     def invoke_role(self, role: tuple[str, str]) -> tuple[list[Node], list[system_message]]:
+        """Invoke the role described by a ``(domain, role name)`` pair."""
+        _deprecation_warning(
+            __name__, f'{self.__class__.__name__}.invoke_role', '', remove=(9, 0)
+        )
         domain = self.env.get_domain(role[0])
         if domain:
             role_func = domain.role(role[1])
@@ -681,11 +798,11 @@ def normalize_intersphinx_mapping(app: Sphinx, config: Config) -> None:
             config.intersphinx_mapping.pop(key)
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
-    app.add_config_value('intersphinx_mapping', {}, True)
-    app.add_config_value('intersphinx_cache_limit', 5, False)
-    app.add_config_value('intersphinx_timeout', None, False)
-    app.add_config_value('intersphinx_disabled_reftypes', ['std:doc'], True)
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_config_value('intersphinx_mapping', {}, 'env')
+    app.add_config_value('intersphinx_cache_limit', 5, '')
+    app.add_config_value('intersphinx_timeout', None, '')
+    app.add_config_value('intersphinx_disabled_reftypes', ['std:doc'], 'env')
     app.connect('config-inited', normalize_intersphinx_mapping, priority=800)
     app.connect('builder-inited', load_mappings)
     app.connect('source-read', install_dispatcher)

sphinx/ext/linkcode.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 
 class LinkcodeError(SphinxError):
@@ -71,7 +72,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
             signode += onlynode
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('doctree-read', doctree_read)
     app.add_config_value('linkcode_resolve', None, '')
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

sphinx/ext/mathjax.py

@@ -21,6 +21,7 @@ from sphinx.util.math import get_node_equation_number
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
     from sphinx.writers.html import HTML5Translator
 
 # more information for mathjax secure url is here:
@@ -109,7 +110,7 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: dict
         builder.add_js_file(app.config.mathjax_path, **options)
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_html_math_renderer('mathjax',
                                (html_visit_math, None),
                                (html_visit_displaymath, None))

sphinx/ext/napoleon/__init__.py

@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import sphinx
 from sphinx.application import Sphinx
 from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
 from sphinx.util import inspect
 
+if TYPE_CHECKING:
+    from sphinx.config import _ConfigRebuild
+    from sphinx.util.typing import ExtensionMetadata
+
 
 class Config:
     """Sphinx napoleon extension settings in `conf.py`.
@@ -261,8 +265,9 @@ class Config:
         Use the type annotations of class attributes that are documented in the docstring
         but do not have a type in the docstring.
 
-    """
-    _config_values = {
+    """  # NoQA: D301
+
+    _config_values: dict[str, tuple[Any, _ConfigRebuild]] = {
         'napoleon_google_docstring': (True, 'env'),
         'napoleon_numpy_docstring': (True, 'env'),
         'napoleon_include_init_with_doc': (False, 'env'),
@@ -288,7 +293,7 @@ class Config:
             setattr(self, name, value)
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """Sphinx extension setup function.
 
     When the extension is loaded, Sphinx imports this module and executes
@@ -326,7 +331,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
 
 
 def _patch_python_domain() -> None:
-    from sphinx.domains.python import PyObject, PyTypedField
+    from sphinx.domains.python._object import PyObject, PyTypedField
     from sphinx.locale import _
     for doc_field in PyObject.doc_field_types:
         if doc_field.name == 'parameter':
@@ -335,7 +340,7 @@ def _patch_python_domain() -> None:
     PyObject.doc_field_types.append(
         PyTypedField('keyword', label=_('Keyword Arguments'),
                      names=('keyword', 'kwarg', 'kwparam'),
-                     typerolename='obj', typenames=('paramtype', 'kwtype'),
+                     typerolename='class', typenames=('paramtype', 'kwtype'),
                      can_collapse=True))
 
 
@@ -386,7 +391,7 @@ def _process_docstring(app: Sphinx, what: str, name: str, obj: Any,
         docstring = GoogleDocstring(result_lines, app.config, app, what, name,
                                     obj, options)
         result_lines = docstring.lines()
-    lines[:] = result_lines[:]
+    lines[:] = result_lines.copy()
 
 
 def _skip_member(app: Sphinx, what: str, name: str, obj: Any,

sphinx/ext/napoleon/docstring.py

@@ -7,6 +7,7 @@ import contextlib
 import inspect
 import re
 from functools import partial
+from itertools import starmap
 from typing import TYPE_CHECKING, Any, Callable
 
 from sphinx.locale import _, __
@@ -14,6 +15,8 @@ from sphinx.util import logging
 from sphinx.util.typing import get_type_hints, stringify_annotation
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from sphinx.application import Sphinx
     from sphinx.config import Config as SphinxConfig
 
@@ -145,7 +148,7 @@ class GoogleDocstring:
     """
 
     _name_rgx = re.compile(r"^\s*((?::(?P<role>\S+):)?`(?P<name>~?[a-zA-Z0-9_.-]+)`|"
-                           r" (?P<name2>~?[a-zA-Z0-9_.-]+))\s*", re.X)
+                           r" (?P<name2>~?[a-zA-Z0-9_.-]+))\s*", re.VERBOSE)
 
     def __init__(
         self,
@@ -304,19 +307,18 @@ class GoogleDocstring:
             _type = _convert_type_spec(_type, self._config.napoleon_type_aliases or {})
 
         indent = self._get_indent(line) + 1
-        _descs = [_desc] + self._dedent(self._consume_indented_block(indent))
+        _descs = [_desc, *self._dedent(self._consume_indented_block(indent))]
         _descs = self.__class__(_descs, self._config).lines()
         return _name, _type, _descs
 
     def _consume_fields(self, parse_type: bool = True, prefer_type: bool = False,
                         multiple: bool = False) -> list[tuple[str, str, list[str]]]:
         self._consume_empty()
-        fields = []
+        fields: list[tuple[str, str, list[str]]] = []
         while not self._is_section_break():
             _name, _type, _desc = self._consume_field(parse_type, prefer_type)
             if multiple and _name:
-                for name in _name.split(","):
-                    fields.append((name.strip(), _type, _desc))
+                fields.extend((name.strip(), _type, _desc) for name in _name.split(","))
             elif _name or _type or _desc:
                 fields.append((_name, _type, _desc))
         return fields
@@ -327,7 +329,7 @@ class GoogleDocstring:
         if not colon or not _desc:
             _type, _desc = _desc, _type
             _desc += colon
-        _descs = [_desc] + self._dedent(self._consume_to_end())
+        _descs = [_desc, *self._dedent(self._consume_to_end())]
         _descs = self.__class__(_descs, self._config).lines()
         return _type, _descs
 
@@ -399,15 +401,15 @@ class GoogleDocstring:
 
     def _fix_field_desc(self, desc: list[str]) -> list[str]:
         if self._is_list(desc):
-            desc = [''] + desc
+            desc = ['', *desc]
         elif desc[0].endswith('::'):
             desc_block = desc[1:]
             indent = self._get_indent(desc[0])
             block_indent = self._get_initial_indent(desc_block)
             if block_indent > indent:
-                desc = [''] + desc
+                desc = ['', *desc]
             else:
-                desc = ['', desc[0]] + self._indent(desc_block, 4)
+                desc = ['', desc[0], *self._indent(desc_block, 4)]
         return desc
 
     def _format_admonition(self, admonition: str, lines: list[str]) -> list[str]:
@@ -416,7 +418,7 @@ class GoogleDocstring:
             return [f'.. {admonition}:: {lines[0].strip()}', '']
         elif lines:
             lines = self._indent(self._dedent(lines), 3)
-            return ['.. %s::' % admonition, ''] + lines + ['']
+            return ['.. %s::' % admonition, '', *lines, '']
         else:
             return ['.. %s::' % admonition, '']
 
@@ -453,7 +455,7 @@ class GoogleDocstring:
 
             if _type:
                 lines.append(f':{type_role} {_name}: {_type}')
-        return lines + ['']
+        return [*lines, '']
 
     def _format_field(self, _name: str, _type: str, _desc: list[str]) -> list[str]:
         _desc = self._strip_empty(_desc)
@@ -480,7 +482,7 @@ class GoogleDocstring:
             if _desc[0]:
                 return [field + _desc[0]] + _desc[1:]
             else:
-                return [field] + _desc
+                return [field, *_desc]
         else:
             return [field]
 
@@ -537,7 +539,7 @@ class GoogleDocstring:
         return [(' ' * n) + line for line in lines]
 
     def _is_indented(self, line: str, indent: int = 1) -> bool:
-        for i, s in enumerate(line):  # noqa: SIM110
+        for i, s in enumerate(line):  # NoQA: SIM110
             if i >= indent:
                 return True
             elif not s.isspace():
@@ -623,7 +625,7 @@ class GoogleDocstring:
                     self._is_in_section = True
                     self._section_indent = self._get_current_indent()
                     if _directive_regex.match(section):
-                        lines = [section] + self._consume_to_next_section()
+                        lines = [section, *self._consume_to_next_section()]
                     else:
                         lines = self._sections[section.lower()](section)
                 finally:
@@ -711,7 +713,7 @@ class GoogleDocstring:
         else:
             header = '.. rubric:: %s' % section
         if lines:
-            return [header, ''] + lines + ['']
+            return [header, '', *lines, '']
         else:
             return [header, '']
 
@@ -733,7 +735,7 @@ class GoogleDocstring:
                 if 'no-index' in self._opt or 'noindex' in self._opt:
                     lines.append('   :no-index:')
             if _desc:
-                lines.extend([''] + self._indent(_desc, 3))
+                lines.extend(['', *self._indent(_desc, 3)])
             lines.append('')
         return lines
 
@@ -888,7 +890,7 @@ def _recombine_set_tokens(tokens: list[str]) -> list[str]:
     token_queue = collections.deque(tokens)
     keywords = ("optional", "default")
 
-    def takewhile_set(tokens):
+    def takewhile_set(tokens: collections.deque[str]) -> Iterator[str]:
         open_braces = 0
         previous_token = None
         while True:
@@ -924,7 +926,7 @@ def _recombine_set_tokens(tokens: list[str]) -> list[str]:
             if open_braces == 0:
                 break
 
-    def combine_set(tokens):
+    def combine_set(tokens: collections.deque[str]) -> Iterator[str]:
         while True:
             try:
                 token = tokens.popleft()
@@ -941,7 +943,7 @@ def _recombine_set_tokens(tokens: list[str]) -> list[str]:
 
 
 def _tokenize_type_spec(spec: str) -> list[str]:
-    def postprocess(item):
+    def postprocess(item: str) -> list[str]:
         if _default_regex.match(item):
             default = item[:7]
             # can't be separated by anything other than a single space
@@ -962,7 +964,7 @@ def _tokenize_type_spec(spec: str) -> list[str]:
 
 
 def _token_type(token: str, location: str | None = None) -> str:
-    def is_numeric(token):
+    def is_numeric(token: str) -> bool:
         try:
             # use complex to make sure every numeric value is detected as literal
             complex(token)
@@ -1026,7 +1028,7 @@ def _convert_numpy_type_spec(
     if translations is None:
         translations = {}
 
-    def convert_obj(obj, translations, default_translation):
+    def convert_obj(obj: str, translations: dict[str, str], default_translation: str) -> str:
         translation = translations.get(obj, obj)
 
         # use :class: (the default) only if obj is not a standard singleton
@@ -1155,6 +1157,7 @@ class NumpyDocstring(GoogleDocstring):
             The lines of the docstring in a list.
 
     """
+
     def __init__(
         self,
         docstring: str | list[str],
@@ -1180,13 +1183,13 @@ class NumpyDocstring(GoogleDocstring):
         elif filepath is None:
             filepath = ""
 
-        return ":".join([filepath, "docstring of %s" % name])
+        return f"{filepath}:docstring of {name}"
 
     def _escape_args_and_kwargs(self, name: str) -> str:
         func = super()._escape_args_and_kwargs
 
         if ", " in name:
-            return ", ".join(func(param) for param in name.split(", "))
+            return ", ".join(map(func, name.split(", ")))
         else:
             return func(name)
 
@@ -1233,7 +1236,7 @@ class NumpyDocstring(GoogleDocstring):
         line1, line2 = self._lines.get(0), self._lines.get(1)
         return (not self._lines or
                 self._is_section_header() or
-                ['', ''] == [line1, line2] or
+                (line1 == line2 == '') or
                 (self._is_in_section and
                     line1 and
                     not self._is_indented(line1, self._section_indent)))
@@ -1269,7 +1272,7 @@ class NumpyDocstring(GoogleDocstring):
         func_name1, func_name2, :meth:`func_name`, func_name3
 
         """
-        items = []
+        items: list[tuple[str, list[str], str | None]] = []
 
         def parse_item_name(text: str) -> tuple[str, str | None]:
             """Match ':role:`name`' or 'name'"""
@@ -1286,10 +1289,12 @@ class NumpyDocstring(GoogleDocstring):
             if not name:
                 return
             name, role = parse_item_name(name)
-            items.append((name, list(rest), role))
-            del rest[:]
+            items.append((name, rest.copy(), role))
+            rest.clear()
 
-        def translate(func, description, role):
+        def translate(
+            func: str, description: list[str], role: str | None,
+        ) -> tuple[str, list[str], str | None]:
             translations = self._config.napoleon_type_aliases
             if role is not None or not translations:
                 return func, description, role
@@ -1336,10 +1341,7 @@ class NumpyDocstring(GoogleDocstring):
             return []
 
         # apply type aliases
-        items = [
-            translate(func, description, role)
-            for func, description, role in items
-        ]
+        items = list(starmap(translate, items))
 
         lines: list[str] = []
         last_had_desc = True

sphinx/ext/todo.py

@@ -7,7 +7,9 @@ with a backlink to the original location.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, cast
+import functools
+import operator
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -26,7 +28,7 @@ if TYPE_CHECKING:
 
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
-    from sphinx.util.typing import OptionSpec
+    from sphinx.util.typing import ExtensionMetadata, OptionSpec
     from sphinx.writers.html import HTML5Translator
     from sphinx.writers.latex import LaTeXTranslator
 
@@ -51,7 +53,7 @@ class Todo(BaseAdmonition, SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'class': directives.class_option,
         'name': directives.unchanged,
     }
@@ -85,7 +87,7 @@ class TodoDomain(Domain):
     def clear_doc(self, docname: str) -> None:
         self.todos.pop(docname, None)
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict) -> None:
+    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
         for docname in docnames:
             self.todos[docname] = otherdata['todos'][docname]
 
@@ -110,7 +112,7 @@ class TodoList(SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         # Simply insert an empty todolist node which will be replaced later
@@ -129,7 +131,8 @@ class TodoListProcessor:
         self.process(doctree, docname)
 
     def process(self, doctree: nodes.document, docname: str) -> None:
-        todos: list[todo_node] = sum(self.domain.todos.values(), [])
+        todos: list[todo_node] = functools.reduce(
+            operator.iadd, self.domain.todos.values(), [])
         for node in list(doctree.findall(todolist)):
             if not self.config.todo_include_todos:
                 node.parent.remove(node)
@@ -221,7 +224,7 @@ def latex_depart_todo_node(self: LaTeXTranslator, node: todo_node) -> None:
     self.body.append('\\end{sphinxadmonition}\n')
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_event('todo-defined')
     app.add_config_value('todo_include_todos', False, 'html')
     app.add_config_value('todo_link_only', False, 'html')