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

sphinx/util/docutils.py

@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
 report_re = re.compile('^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\\d+)?\\) ')
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    from collections.abc import Iterator
     from types import ModuleType
 
     from docutils.frontend import Values
@@ -38,29 +38,12 @@ if TYPE_CHECKING:
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import RoleFunction
 
-# deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS = {
-    '__version_info__': (docutils.__version_info__, 'docutils.__version_info__'),
-}
-
-
-def __getattr__(name):
-    if name not in _DEPRECATED_OBJECTS:
-        msg = f'module {__name__!r} has no attribute {name!r}'
-        raise AttributeError(msg)
-
-    from sphinx.deprecation import _deprecation_warning
-
-    deprecated_object, canonical_name = _DEPRECATED_OBJECTS[name]
-    _deprecation_warning(__name__, name, canonical_name, remove=(7, 0))
-    return deprecated_object
-
 
 additional_nodes: set[type[Element]] = set()
 
 
 @contextmanager
-def docutils_namespace() -> Generator[None, None, None]:
+def docutils_namespace() -> Iterator[None]:
     """Create namespace for reST parsers."""
     try:
         _directives = copy(directives._directives)  # type: ignore[attr-defined]
@@ -101,7 +84,7 @@ def register_role(name: str, role: RoleFunction) -> None:
     This modifies global state of docutils.  So it is better to use this
     inside ``docutils_namespace()`` to prevent side-effects.
     """
-    roles.register_local_role(name, role)
+    roles.register_local_role(name, role)  # type: ignore[arg-type]
 
 
 def unregister_role(name: str) -> None:
@@ -138,7 +121,7 @@ def unregister_node(node: type[Element]) -> None:
 
 
 @contextmanager
-def patched_get_language() -> Generator[None, None, None]:
+def patched_get_language() -> Iterator[None]:
     """Patch docutils.languages.get_language() temporarily.
 
     This ignores the second argument ``reporter`` to suppress warnings.
@@ -150,7 +133,7 @@ def patched_get_language() -> Generator[None, None, None]:
         return get_language(language_code)
 
     try:
-        docutils.languages.get_language = patched_get_language
+        docutils.languages.get_language = patched_get_language  # type: ignore[assignment]
         yield
     finally:
         # restore original implementations
@@ -158,7 +141,7 @@ def patched_get_language() -> Generator[None, None, None]:
 
 
 @contextmanager
-def patched_rst_get_language() -> Generator[None, None, None]:
+def patched_rst_get_language() -> Iterator[None]:
     """Patch docutils.parsers.rst.languages.get_language().
     Starting from docutils 0.17, get_language() in ``rst.languages``
     also has a reporter, which needs to be disabled temporarily.
@@ -174,7 +157,7 @@ def patched_rst_get_language() -> Generator[None, None, None]:
         return get_language(language_code)
 
     try:
-        docutils.parsers.rst.languages.get_language = patched_get_language
+        docutils.parsers.rst.languages.get_language = patched_get_language  # type: ignore[assignment]
         yield
     finally:
         # restore original implementations
@@ -182,7 +165,7 @@ def patched_rst_get_language() -> Generator[None, None, None]:
 
 
 @contextmanager
-def using_user_docutils_conf(confdir: str | None) -> Generator[None, None, None]:
+def using_user_docutils_conf(confdir: str | None) -> Iterator[None]:
     """Let docutils know the location of ``docutils.conf`` for Sphinx."""
     try:
         docutilsconfig = os.environ.get('DOCUTILSCONFIG', None)
@@ -198,8 +181,8 @@ def using_user_docutils_conf(confdir: str | None) -> Generator[None, None, None]
 
 
 @contextmanager
-def du19_footnotes() -> Generator[None, None, None]:
-    def visit_footnote(self, node):
+def du19_footnotes() -> Iterator[None]:
+    def visit_footnote(self: HTMLTranslator, node: Element) -> None:
         label_style = self.settings.footnote_references
         if not isinstance(node.previous_sibling(), type(node)):
             self.body.append(f'<aside class="footnote-list {label_style}">\n')
@@ -207,7 +190,7 @@ def du19_footnotes() -> Generator[None, None, None]:
                                        classes=[node.tagname, label_style],
                                        role="note"))
 
-    def depart_footnote(self, node):
+    def depart_footnote(self: HTMLTranslator, node: Element) -> None:
         self.body.append('</aside>\n')
         if not isinstance(node.next_node(descend=False, siblings=True),
                           type(node)):
@@ -231,7 +214,7 @@ def du19_footnotes() -> Generator[None, None, None]:
 
 
 @contextmanager
-def patch_docutils(confdir: str | None = None) -> Generator[None, None, None]:
+def patch_docutils(confdir: str | None = None) -> Iterator[None]:
     """Patch to docutils temporarily."""
     with patched_get_language(), \
          patched_rst_get_language(), \
@@ -263,8 +246,8 @@ class CustomReSTDispatcher:
         self.directive_func = directives.directive
         self.role_func = roles.role
 
-        directives.directive = self.directive
-        roles.role = self.role
+        directives.directive = self.directive  # type: ignore[assignment]
+        roles.role = self.role  # type: ignore[assignment]
 
     def disable(self) -> None:
         directives.directive = self.directive_func
@@ -290,6 +273,7 @@ class sphinx_domains(CustomReSTDispatcher):
     """Monkey-patch directive and role dispatch, so that domain-specific
     markup takes precedence.
     """
+
     def __init__(self, env: BuildEnvironment) -> None:
         self.env = env
         super().__init__()
@@ -354,7 +338,7 @@ class WarningStream:
 
 class LoggingReporter(Reporter):
     @classmethod
-    def from_reporter(cls, reporter: Reporter) -> LoggingReporter:
+    def from_reporter(cls: type[LoggingReporter], reporter: Reporter) -> LoggingReporter:
         """Create an instance of LoggingReporter from other reporter object."""
         return cls(reporter.source, reporter.report_level, reporter.halt_level,
                    reporter.debug_flag, reporter.error_handler)
@@ -375,16 +359,16 @@ class NullReporter(Reporter):
 
 
 @contextmanager
-def switch_source_input(state: State, content: StringList) -> Generator[None, None, None]:
+def switch_source_input(state: State, content: StringList) -> Iterator[None]:
     """Switch current source input of state temporarily."""
     try:
         # remember the original ``get_source_and_line()`` method
         gsal = state.memo.reporter.get_source_and_line  # type: ignore[attr-defined]
 
         # replace it by new one
-        state_machine = StateMachine([], None)  # type: ignore[arg-type]
+        state_machine: StateMachine[None] = StateMachine([], None)  # type: ignore[arg-type]
         state_machine.input_lines = content
-        state.memo.reporter.get_source_and_line = state_machine.get_source_and_line  # type: ignore[attr-defined]  # noqa: E501
+        state.memo.reporter.get_source_and_line = state_machine.get_source_and_line  # type: ignore[attr-defined]  # NoQA: E501
 
         yield
     finally:
@@ -451,6 +435,7 @@ class SphinxRole:
     .. note:: The subclasses of this class might not work with docutils.
               This class is strongly coupled with Sphinx.
     """
+
     name: str         #: The role name actually used in the document.
     rawtext: str      #: A string containing the entire interpreted text input.
     text: str         #: The interpreted text content.
@@ -519,6 +504,7 @@ class ReferenceRole(SphinxRole):
     the role.  The parsed result; link title and target will be stored to
     ``self.title`` and ``self.target``.
     """
+
     has_explicit_title: bool    #: A boolean indicates the role has explicit title or not.
     disabled: bool              #: A boolean indicates the reference is disabled.
     title: str                  #: The link title for the interpreted text.

sphinx/util/exceptions.py

@@ -6,7 +6,7 @@ from tempfile import NamedTemporaryFile
 from typing import TYPE_CHECKING
 
 from sphinx.errors import SphinxParallelError
-from sphinx.util.console import strip_colors
+from sphinx.util.console import strip_escape_sequences
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -31,7 +31,8 @@ def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
         last_msgs = exts_list = ''
     else:
         extensions = app.extensions.values()
-        last_msgs = '\n'.join(f'#   {strip_colors(s).strip()}' for s in app.messagelog)
+        last_msgs = '\n'.join(f'#   {strip_escape_sequences(s).strip()}'
+                              for s in app.messagelog)
         exts_list = '\n'.join(f'#   {ext.name} ({ext.version})' for ext in extensions
                               if ext.version != 'builtin')
 

sphinx/util/fileutil.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import os
 import posixpath
-from typing import TYPE_CHECKING, Callable
+from typing import TYPE_CHECKING, Any, Callable
 
 from docutils.utils import relative_path
 
@@ -16,7 +16,7 @@ if TYPE_CHECKING:
 
 
 def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLike[str],
-                    context: dict | None = None,
+                    context: dict[str, Any] | None = None,
                     renderer: BaseRenderer | None = None) -> None:
     """Copy an asset file to destination.
 
@@ -53,7 +53,7 @@ def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLi
 
 def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[str],
                excluded: PathMatcher = lambda path: False,
-               context: dict | None = None, renderer: BaseRenderer | None = None,
+               context: dict[str, Any] | None = None, renderer: BaseRenderer | None = None,
                onerror: Callable[[str, Exception], None] | None = None) -> None:
     """Copy asset files to destination recursively.
 
@@ -80,8 +80,8 @@ def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[st
         return
 
     for root, dirs, files in os.walk(source, followlinks=True):
-        reldir = relative_path(source, root)  # type: ignore[arg-type]
-        for dir in dirs[:]:
+        reldir = relative_path(source, root)
+        for dir in dirs.copy():
             if excluded(posixpath.join(reldir, dir)):
                 dirs.remove(dir)
             else:

sphinx/util/http_date.py

@@ -5,16 +5,23 @@ Reference: https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1
 
 import time
 import warnings
-from email.utils import formatdate, parsedate_tz
+from email.utils import parsedate_tz
 
 from sphinx.deprecation import RemovedInSphinx90Warning
 
+_WEEKDAY_NAME = ('Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun')
+_MONTH_NAME = ('',  # Placeholder for indexing purposes
+               'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+               'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec')
 _GMT_OFFSET = float(time.localtime().tm_gmtoff)
 
 
 def epoch_to_rfc1123(epoch: float) -> str:
     """Return HTTP-date string from epoch offset."""
-    return formatdate(epoch, usegmt=True)
+    yr, mn, dd, hh, mm, ss, wd, _yd, _tz = time.gmtime(epoch)
+    weekday_name = _WEEKDAY_NAME[wd]
+    month = _MONTH_NAME[mn]
+    return f'{weekday_name}, {dd:02} {month} {yr:04} {hh:02}:{mm:02}:{ss:02} GMT'
 
 
 def rfc1123_to_epoch(rfc1123: str) -> float:

sphinx/util/i18n.py

@@ -6,7 +6,7 @@ import os
 import re
 from datetime import datetime, timezone
 from os import path
-from typing import TYPE_CHECKING, Callable, NamedTuple
+from typing import TYPE_CHECKING, NamedTuple
 
 import babel.dates
 from babel.messages.mofile import write_mo
@@ -18,10 +18,41 @@ from sphinx.util import logging
 from sphinx.util.osutil import SEP, canon_path, relpath
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    import datetime as dt
+    from collections.abc import Iterator
+    from typing import Protocol, Union
+
+    from babel.core import Locale
 
     from sphinx.environment import BuildEnvironment
 
+    class DateFormatter(Protocol):
+        def __call__(  # NoQA: E704
+            self,
+            date: dt.date | None = ...,
+            format: str = ...,
+            locale: str | Locale | None = ...,
+        ) -> str: ...
+
+    class TimeFormatter(Protocol):
+        def __call__(  # NoQA: E704
+            self,
+            time: dt.time | dt.datetime | float | None = ...,
+            format: str = ...,
+            tzinfo: dt.tzinfo | None = ...,
+            locale: str | Locale | None = ...,
+        ) -> str: ...
+
+    class DatetimeFormatter(Protocol):
+        def __call__(  # NoQA: E704
+            self,
+            datetime: dt.date | dt.time | float | None = ...,
+            format: str = ...,
+            tzinfo: dt.tzinfo | None = ...,
+            locale: str | Locale | None = ...,
+        ) -> str: ...
+
+    Formatter = Union[DateFormatter, TimeFormatter, DatetimeFormatter]
 
 logger = logging.getLogger(__name__)
 
@@ -81,7 +112,7 @@ class CatalogRepository:
         self.encoding = encoding
 
     @property
-    def locale_dirs(self) -> Generator[str, None, None]:
+    def locale_dirs(self) -> Iterator[str]:
         if not self.language:
             return
 
@@ -94,14 +125,13 @@ class CatalogRepository:
                 logger.verbose(__('locale_dir %s does not exist'), locale_path)
 
     @property
-    def pofiles(self) -> Generator[tuple[str, str], None, None]:
+    def pofiles(self) -> Iterator[tuple[str, str]]:
         for locale_dir in self.locale_dirs:
             basedir = path.join(locale_dir, self.language, 'LC_MESSAGES')
             for root, dirnames, filenames in os.walk(basedir):
                 # skip dot-directories
-                for dirname in dirnames:
-                    if dirname.startswith('.'):
-                        dirnames.remove(dirname)
+                for dirname in [d for d in dirnames if d.startswith('.')]:
+                    dirnames.remove(dirname)
 
                 for filename in filenames:
                     if filename.endswith('.po'):
@@ -109,7 +139,7 @@ class CatalogRepository:
                         yield basedir, relpath(fullpath, basedir)
 
     @property
-    def catalogs(self) -> Generator[CatalogInfo, None, None]:
+    def catalogs(self) -> Iterator[CatalogInfo]:
         for basedir, filename in self.pofiles:
             domain = canon_path(path.splitext(filename)[0])
             yield CatalogInfo(basedir, domain, self.encoding)
@@ -170,7 +200,7 @@ date_format_re = re.compile('(%s)' % '|'.join(date_format_mappings))
 
 
 def babel_format_date(date: datetime, format: str, locale: str,
-                      formatter: Callable = babel.dates.format_date) -> str:
+                      formatter: Formatter = babel.dates.format_date) -> str:
     # Check if we have the tzinfo attribute. If not we cannot do any time
     # related formats.
     if not hasattr(date, 'tzinfo'):
@@ -208,6 +238,7 @@ def format_date(
             # Check if we have to use a different babel formatter then
             # format_datetime, because we only want to format a date
             # or a time.
+            function: Formatter
             if token == '%x':
                 function = babel.dates.format_date
             elif token == '%X':