Sphinx 8.2.0rc2__py3-none-any.whl → 8.3.0__py3-none-any.whl

sphinx/__init__.py

@@ -1,24 +1,25 @@
 """The Sphinx documentation toolchain."""
 
-from __future__ import annotations
-
-__version__ = '8.2.0rc2'
-__display_version__ = __version__  # used for command line version
-
 # Keep this file executable as-is in Python 3!
 # (Otherwise getting the version out of it when packaging is impossible.)
 
-import os
+from __future__ import annotations
+
 import warnings
 
-from sphinx.util._pathlib import _StrPath
+# work around flit error in parsing annotated assignments
+try:
+    from sphinx.util._pathlib import _StrPath
+except ImportError:
+    from pathlib import Path as _StrPath  # type: ignore[assignment]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Final
 
-# by default, all DeprecationWarning under sphinx package will be emit.
-# Users can avoid this by using environment variable: PYTHONWARNINGS=
-if 'PYTHONWARNINGS' not in os.environ:
-    from sphinx.deprecation import RemovedInNextVersionWarning
+__version__: Final = '8.3.0'
+__display_version__: Final = __version__  # used for command line version
 
-    warnings.filterwarnings('default', category=RemovedInNextVersionWarning)
 warnings.filterwarnings(
     'ignore',
     'The frontend.Option class .*',
@@ -34,9 +35,9 @@ warnings.filterwarnings(
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (8, 2, 0, 'candidate', 2)
+version_info: Final = (8, 2, 2, 'final', 0)
 
-package_dir = _StrPath(__file__).resolve().parent
+package_dir: Final = _StrPath(__file__).resolve().parent
 
 _in_development = False
 if _in_development:
@@ -45,14 +46,14 @@ if _in_development:
 
     try:
         if ret := subprocess.run(
-            ['git', 'rev-parse', '--short', 'HEAD'],  # NoQA: S607
-            cwd=package_dir,
+            ('git', 'rev-parse', '--short', 'HEAD'),
             capture_output=True,
             check=False,
-            encoding='ascii',
+            cwd=package_dir,
+            encoding='utf-8',
             errors='surrogateescape',
         ).stdout:
-            __display_version__ += '+/' + ret.strip()
+            __display_version__ += f'+/{ret.strip()}'  # type: ignore[misc]
         del ret
     finally:
         del subprocess

sphinx/application.py

@@ -1507,6 +1507,7 @@ class Sphinx:
         elif loading_method == 'defer':
             kwargs['defer'] = 'defer'
 
+        filename = filename or ''
         self.registry.add_js_file(filename, priority=priority, **kwargs)
         with contextlib.suppress(AttributeError):
             self.builder.add_js_file(  # type: ignore[attr-defined]

sphinx/deprecation.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import warnings
 
 
@@ -16,6 +17,12 @@ class RemovedInSphinx10Warning(PendingDeprecationWarning):
 RemovedInNextVersionWarning = RemovedInSphinx90Warning
 
 
+# By default, all Sphinx deprecation warnings will be emitted.
+# To avoid this, set the environment variable: PYTHONWARNINGS=
+if 'PYTHONWARNINGS' not in os.environ:
+    warnings.filterwarnings('default', category=RemovedInNextVersionWarning)
+
+
 def _deprecation_warning(
     module: str,
     attribute: str,

sphinx/ext/apidoc/_extension.py

@@ -217,7 +217,6 @@ def _parse_module_options(
         dest_dir=dest_path,
         module_path=module_path,
         exclude_pattern=exclude_patterns,
-        automodule_options=automodule_options,
         max_depth=max_depth,
         quiet=True,
         follow_links=bool_options['follow_links'],
@@ -226,6 +225,8 @@ def _parse_module_options(
         no_headings=bool_options['no_headings'],
         module_first=bool_options['module_first'],
         implicit_namespaces=bool_options['implicit_namespaces'],
+        automodule_options=automodule_options,
+        header=module_path.name,
     )
 
 

sphinx/ext/autodoc/__init__.py

@@ -291,7 +291,7 @@ def between(
 # This class is used only in ``sphinx.ext.autodoc.directive``,
 # But we define this class here to keep compatibility
 # See: https://github.com/sphinx-doc/sphinx/issues/4538
-class Options(dict[str, Any]):
+class Options(dict[str, Any]):  # NoQA: FURB189
     """A dict/attribute hybrid that returns None on nonexisting keys."""
 
     def copy(self) -> Options:

sphinx/ext/autodoc/directive.py

@@ -52,7 +52,7 @@ AUTODOC_EXTENDABLE_OPTIONS = frozenset({
 })
 
 
-class DummyOptionSpec(dict[str, Callable[[str], str]]):
+class DummyOptionSpec(dict[str, Callable[[str], str]]):  # NoQA: FURB189
     """An option_spec allows any options."""
 
     def __bool__(self) -> bool:

sphinx/ext/autodoc/mock.py

@@ -30,7 +30,7 @@ class _MockObject:
     __sphinx_mock__ = True
     __sphinx_decorator_args__: tuple[Any, ...] = ()
 
-    def __new__(cls, *args: Any, **kwargs: Any) -> Any:
+    def __new__(cls, *args: Any, **kwargs: Any) -> Any:  # NoQA: ARG004
         if len(args) == 3 and isinstance(args[1], tuple):
             superclass = args[1][-1].__class__
             if superclass is cls:

sphinx/ext/napoleon/__init__.py

@@ -11,6 +11,7 @@ from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
 from sphinx.util import inspect
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence, Set
     from typing import Any
 
     from sphinx.config import _ConfigRebuild
@@ -270,27 +271,27 @@ class Config:
 
     """
 
-    _config_values: dict[str, tuple[Any, _ConfigRebuild]] = {
-        'napoleon_google_docstring': (True, 'env'),
-        'napoleon_numpy_docstring': (True, 'env'),
-        'napoleon_include_init_with_doc': (False, 'env'),
-        'napoleon_include_private_with_doc': (False, 'env'),
-        'napoleon_include_special_with_doc': (False, 'env'),
-        'napoleon_use_admonition_for_examples': (False, 'env'),
-        'napoleon_use_admonition_for_notes': (False, 'env'),
-        'napoleon_use_admonition_for_references': (False, 'env'),
-        'napoleon_use_ivar': (False, 'env'),
-        'napoleon_use_param': (True, 'env'),
-        'napoleon_use_rtype': (True, 'env'),
-        'napoleon_use_keyword': (True, 'env'),
-        'napoleon_preprocess_types': (False, 'env'),
-        'napoleon_type_aliases': (None, 'env'),
-        'napoleon_custom_sections': (None, 'env'),
-        'napoleon_attr_annotations': (True, 'env'),
-    }
+    _config_values: Sequence[tuple[str, bool | None, _ConfigRebuild, Set[type]]] = (
+        ('napoleon_google_docstring', True, 'env', frozenset({bool})),
+        ('napoleon_numpy_docstring', True, 'env', frozenset({bool})),
+        ('napoleon_include_init_with_doc', False, 'env', frozenset({bool})),
+        ('napoleon_include_private_with_doc', False, 'env', frozenset({bool})),
+        ('napoleon_include_special_with_doc', False, 'env', frozenset({bool})),
+        ('napoleon_use_admonition_for_examples', False, 'env', frozenset({bool})),
+        ('napoleon_use_admonition_for_notes', False, 'env', frozenset({bool})),
+        ('napoleon_use_admonition_for_references', False, 'env', frozenset({bool})),
+        ('napoleon_use_ivar', False, 'env', frozenset({bool})),
+        ('napoleon_use_param', True, 'env', frozenset({bool})),
+        ('napoleon_use_rtype', True, 'env', frozenset({bool})),
+        ('napoleon_use_keyword', True, 'env', frozenset({bool})),
+        ('napoleon_preprocess_types', False, 'env', frozenset({bool})),
+        ('napoleon_type_aliases', None, 'env', frozenset({dict, NoneType})),
+        ('napoleon_custom_sections', None, 'env', frozenset({list, tuple, NoneType})),
+        ('napoleon_attr_annotations', True, 'env', frozenset({bool})),
+    )
 
     def __init__(self, **settings: Any) -> None:
-        for name, (default, _rebuild) in self._config_values.items():
+        for name, default, _rebuild, _types in self._config_values:
             setattr(self, name, default)
         for name, value in settings.items():
             setattr(self, name, value)
@@ -331,11 +332,9 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('autodoc-process-docstring', _process_docstring)
     app.connect('autodoc-skip-member', _skip_member)
 
-    for name, (default, rebuild) in Config._config_values.items():
-        if isinstance(default, bool):
-            app.add_config_value(name, default, rebuild, types=frozenset({bool}))
-        else:
-            app.add_config_value(name, default, rebuild, types=frozenset({NoneType}))
+    for name, default, rebuild, types in Config._config_values:
+        app.add_config_value(name, default, rebuild, types=types)
+
     return {
         'version': sphinx.__display_version__,
         'parallel_read_safe': True,

sphinx/ext/viewcode.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-import importlib.util
+import importlib
 import operator
 import posixpath
 import traceback
@@ -62,16 +62,20 @@ def _get_full_modname(modname: str, attribute: str) -> str | None:
         num_parts = len(module_path)
         for i in range(num_parts, 0, -1):
             mod_root = '.'.join(module_path[:i])
-            module_spec = importlib.util.find_spec(mod_root)
-            if module_spec is not None:
+            try:
+                # import_module() caches the module in sys.modules
+                module = importlib.import_module(mod_root)
                 break
+            except ModuleNotFoundError:
+                continue
+            except BaseException as exc:
+                # Importing modules may cause any side effects, including
+                # SystemExit, so we need to catch all errors.
+                msg = f"viewcode failed to import '{mod_root}'."
+                raise ImportError(msg) from exc
         else:
             return None
-        # Load and execute the module
-        module = importlib.util.module_from_spec(module_spec)
-        if module_spec.loader is None:
-            return None
-        module_spec.loader.exec_module(module)
+
         if i != num_parts:
             for mod in module_path[i:]:
                 module = getattr(module, mod)

sphinx/highlighting.py

@@ -171,7 +171,7 @@ class PygmentsBridge:
                     lang,
                     location=location,
                     type='misc',
-                    subtype='higlighting_failure',
+                    subtype='highlighting_failure',
                 )
                 lexer = lexer_classes['none'](**opts)
 

sphinx/locale/__init__.py

@@ -8,11 +8,15 @@ from gettext import NullTranslations, translation
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from sphinx import package_dir
+
 if TYPE_CHECKING:
     import os
     from collections.abc import Callable, Iterable
     from typing import Any
 
+_LOCALE_DIR = Path(package_dir, 'locale')
+
 
 class _TranslationProxy:
     """The proxy implementation attempts to be as complete as possible, so that
@@ -140,9 +144,6 @@ def init(
     return translator, has_translation
 
 
-_LOCALE_DIR = Path(__file__).resolve().parent
-
-
 def init_console(
     locale_dir: str | os.PathLike[str] | None = None,
     catalog: str = 'sphinx',