Sphinx 8.0.1__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/util/docutils.py

@@ -24,7 +24,9 @@ from sphinx.util import logging
 from sphinx.util.parsing import nested_parse_to_nodes
 
 logger = logging.getLogger(__name__)
-report_re = re.compile('^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\\d+)?\\) ')
+report_re = re.compile(
+    '^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\\d+)?\\) '
+)
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator  # NoQA: TCH003
@@ -114,8 +116,8 @@ def unregister_node(node: type[Element]) -> None:
     This is inverse of ``nodes._add_nodes_class_names()``.
     """
     if hasattr(nodes.GenericNodeVisitor, 'visit_' + node.__name__):
-        delattr(nodes.GenericNodeVisitor, "visit_" + node.__name__)
-        delattr(nodes.GenericNodeVisitor, "depart_" + node.__name__)
+        delattr(nodes.GenericNodeVisitor, 'visit_' + node.__name__)
+        delattr(nodes.GenericNodeVisitor, 'depart_' + node.__name__)
         delattr(nodes.SparseNodeVisitor, 'visit_' + node.__name__)
         delattr(nodes.SparseNodeVisitor, 'depart_' + node.__name__)
 
@@ -129,7 +131,9 @@ def patched_get_language() -> Iterator[None]:
     """
     from docutils.languages import get_language
 
-    def patched_get_language(language_code: str, reporter: Reporter | None = None) -> Any:
+    def patched_get_language(
+        language_code: str, reporter: Reporter | None = None
+    ) -> Any:
         return get_language(language_code)
 
     try:
@@ -153,7 +157,9 @@ def patched_rst_get_language() -> Iterator[None]:
     """
     from docutils.parsers.rst.languages import get_language
 
-    def patched_get_language(language_code: str, reporter: Reporter | None = None) -> Any:
+    def patched_get_language(
+        language_code: str, reporter: Reporter | None = None
+    ) -> Any:
         return get_language(language_code)
 
     try:
@@ -170,7 +176,9 @@ def using_user_docutils_conf(confdir: str | None) -> Iterator[None]:
     try:
         docutilsconfig = os.environ.get('DOCUTILSCONFIG', None)
         if confdir:
-            os.environ['DOCUTILSCONFIG'] = path.join(path.abspath(confdir), 'docutils.conf')
+            os.environ['DOCUTILSCONFIG'] = path.join(
+                path.abspath(confdir), 'docutils.conf'
+            )
 
         yield
     finally:
@@ -183,9 +191,11 @@ def using_user_docutils_conf(confdir: str | None) -> Iterator[None]:
 @contextmanager
 def patch_docutils(confdir: str | None = None) -> Iterator[None]:
     """Patch to docutils temporarily."""
-    with patched_get_language(), \
-         patched_rst_get_language(), \
-         using_user_docutils_conf(confdir):
+    with (
+        patched_get_language(),
+        patched_rst_get_language(),
+        using_user_docutils_conf(confdir),
+    ):
         yield
 
 
@@ -204,7 +214,7 @@ class CustomReSTDispatcher:
         self.enable()
 
     def __exit__(
-        self, exc_type: type[Exception], exc_value: Exception, traceback: Any,
+        self, exc_type: type[Exception], exc_value: Exception, traceback: Any
     ) -> None:
         self.disable()
 
@@ -219,16 +229,27 @@ class CustomReSTDispatcher:
         directives.directive = self.directive_func
         roles.role = self.role_func
 
-    def directive(self,
-                  directive_name: str, language_module: ModuleType, document: nodes.document,
-                  ) -> tuple[type[Directive] | None, list[system_message]]:
+    def directive(
+        self,
+        directive_name: str,
+        language_module: ModuleType,
+        document: nodes.document,
+    ) -> tuple[type[Directive] | None, list[system_message]]:
         return self.directive_func(directive_name, language_module, document)
 
     def role(
-        self, role_name: str, language_module: ModuleType, lineno: int, reporter: Reporter,
+        self,
+        role_name: str,
+        language_module: ModuleType,
+        lineno: int,
+        reporter: Reporter,
     ) -> tuple[RoleFunction, list[system_message]]:
-        return self.role_func(role_name, language_module,  # type: ignore[return-value]
-                              lineno, reporter)
+        return self.role_func(
+            role_name,
+            language_module,  # type: ignore[return-value]
+            lineno,
+            reporter,
+        )
 
 
 class ElementLookupError(Exception):
@@ -258,7 +279,9 @@ class sphinx_domains(CustomReSTDispatcher):
                 if element is not None:
                     return element, []
             else:
-                logger.warning(_('unknown directive or role name: %s:%s'), domain_name, name)
+                logger.warning(
+                    _('unknown directive or role name: %s:%s'), domain_name, name
+                )
         # else look in the default domain
         else:
             def_domain = self.env.temp_data.get('default_domain')
@@ -268,22 +291,29 @@ class sphinx_domains(CustomReSTDispatcher):
                     return element, []
 
         # always look in the std domain
-        element = getattr(self.env.get_domain('std'), type)(name)
+        element = getattr(self.env.domains.standard_domain, type)(name)
         if element is not None:
             return element, []
 
         raise ElementLookupError
 
-    def directive(self,
-                  directive_name: str, language_module: ModuleType, document: nodes.document,
-                  ) -> tuple[type[Directive] | None, list[system_message]]:
+    def directive(
+        self,
+        directive_name: str,
+        language_module: ModuleType,
+        document: nodes.document,
+    ) -> tuple[type[Directive] | None, list[system_message]]:
         try:
             return self.lookup_domain_element('directive', directive_name)
         except ElementLookupError:
             return super().directive(directive_name, language_module, document)
 
     def role(
-        self, role_name: str, language_module: ModuleType, lineno: int, reporter: Reporter,
+        self,
+        role_name: str,
+        language_module: ModuleType,
+        lineno: int,
+        reporter: Reporter,
     ) -> tuple[RoleFunction, list[system_message]]:
         try:
             return self.lookup_domain_element('role', role_name)
@@ -295,26 +325,39 @@ class WarningStream:
     def write(self, text: str) -> None:
         matched = report_re.search(text)
         if not matched:
-            logger.warning(text.rstrip("\r\n"), type="docutils")
+            logger.warning(text.rstrip('\r\n'), type='docutils')
         else:
             location, type, level = matched.groups()
             message = report_re.sub('', text).rstrip()
-            logger.log(type, message, location=location, type="docutils")
+            logger.log(type, message, location=location, type='docutils')
 
 
 class LoggingReporter(Reporter):
     @classmethod
-    def from_reporter(cls: type[LoggingReporter], 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)
+        return cls(
+            reporter.source,
+            reporter.report_level,
+            reporter.halt_level,
+            reporter.debug_flag,
+            reporter.error_handler,
+        )
 
-    def __init__(self, source: str, report_level: int = Reporter.WARNING_LEVEL,
-                 halt_level: int = Reporter.SEVERE_LEVEL, debug: bool = False,
-                 error_handler: str = 'backslashreplace') -> None:
+    def __init__(
+        self,
+        source: str,
+        report_level: int = Reporter.WARNING_LEVEL,
+        halt_level: int = Reporter.SEVERE_LEVEL,
+        debug: bool = False,
+        error_handler: str = 'backslashreplace',
+    ) -> None:
         stream = cast(IO, WarningStream())
-        super().__init__(source, report_level, halt_level,
-                         stream, debug, error_handler=error_handler)
+        super().__init__(
+            source, report_level, halt_level, stream, debug, error_handler=error_handler
+        )
 
 
 class NullReporter(Reporter):
@@ -351,8 +394,13 @@ class SphinxFileOutput(FileOutput):
         super().__init__(**kwargs)
 
     def write(self, data: str) -> str:
-        if (self.destination_path and self.autoclose and 'b' not in self.mode and
-                self.overwrite_if_changed and os.path.exists(self.destination_path)):
+        if (
+            self.destination_path
+            and self.autoclose
+            and 'b' not in self.mode
+            and self.overwrite_if_changed
+            and os.path.exists(self.destination_path)
+        ):
             with open(self.destination_path, encoding=self.encoding) as f:
                 # skip writing: content not changed
                 if f.read() == data:
@@ -416,7 +464,9 @@ class SphinxDirective(Directive):
             return f'<unknown>:{line}'
         return ''
 
-    def parse_content_to_nodes(self, allow_section_headings: bool = False) -> list[Node]:
+    def parse_content_to_nodes(
+        self, allow_section_headings: bool = False
+    ) -> list[Node]:
         """Parse the directive's content into nodes.
 
         :param allow_section_headings:
@@ -437,7 +487,12 @@ class SphinxDirective(Directive):
         )
 
     def parse_text_to_nodes(
-        self, text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False,
+        self,
+        text: str = '',
+        /,
+        *,
+        offset: int = -1,
+        allow_section_headings: bool = False,
     ) -> list[Node]:
         """Parse *text* into nodes.
 
@@ -465,7 +520,7 @@ class SphinxDirective(Directive):
         )
 
     def parse_inline(
-        self, text: str, *, lineno: int = -1,
+        self, text: str, *, lineno: int = -1
     ) -> tuple[list[Node], list[system_message]]:
         """Parse *text* as inline elements.
 
@@ -496,6 +551,7 @@ class SphinxRole:
               This class is strongly coupled with Sphinx.
     """
 
+    # fmt: off
     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.
@@ -507,10 +563,18 @@ class SphinxRole:
     #: A list of strings, the directive content for customisation
     #: (from the "role" directive).
     content: Sequence[str]
-
-    def __call__(self, name: str, rawtext: str, text: str, lineno: int,
-                 inliner: Inliner, options: dict | None = None, content: Sequence[str] = (),
-                 ) -> tuple[list[Node], list[system_message]]:
+    # fmt: on
+
+    def __call__(
+        self,
+        name: str,
+        rawtext: str,
+        text: str,
+        lineno: int,
+        inliner: Inliner,
+        options: dict | None = None,
+        content: Sequence[str] = (),
+    ) -> tuple[list[Node], list[system_message]]:
         self.rawtext = rawtext
         self.text = unescape(text)
         self.lineno = lineno
@@ -585,17 +649,26 @@ class ReferenceRole(SphinxRole):
     .. versionadded:: 2.0
     """
 
+    # fmt: off
     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.
     target: str                 #: The link target for the interpreted text.
+    # fmt: on
 
     # \x00 means the "<" was backslash-escaped
     explicit_title_re = re.compile(r'^(.+?)\s*(?<!\x00)<(.*?)>$', re.DOTALL)
 
-    def __call__(self, name: str, rawtext: str, text: str, lineno: int,
-                 inliner: Inliner, options: dict | None = None, content: Sequence[str] = (),
-                 ) -> tuple[list[Node], list[system_message]]:
+    def __call__(
+        self,
+        name: str,
+        rawtext: str,
+        text: str,
+        lineno: int,
+        inliner: Inliner,
+        options: dict | None = None,
+        content: Sequence[str] = (),
+    ) -> tuple[list[Node], list[system_message]]:
         if options is None:
             options = {}
 
@@ -698,6 +771,7 @@ def new_document(source_path: str, settings: Any = None) -> nodes.document:
 
     # Create a new instance of nodes.document using cached reporter
     from sphinx import addnodes
+
     document = addnodes.document(settings, reporter, source=source_path)
     document.note_source(source_path, -1)
     return document

sphinx/util/exceptions.py

@@ -31,12 +31,18 @@ def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
         last_msgs = exts_list = ''
     else:
         extensions = app.extensions.values()
-        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')
+        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'
+        )
 
-    with NamedTemporaryFile('w', suffix='.log', prefix='sphinx-err-', delete=False) as f:
+    with NamedTemporaryFile(
+        'w', suffix='.log', prefix='sphinx-err-', delete=False
+    ) as f:
         f.write(f"""\
 # Platform:         {sys.platform}; ({platform.platform()})
 # Sphinx version:   {sphinx.__display_version__}

sphinx/util/fileutil.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 import posixpath
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from docutils.utils import relative_path
@@ -34,11 +35,14 @@ def _template_basename(filename: str | os.PathLike[str]) -> str | None:
     return None
 
 
-def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLike[str],
-                    context: dict[str, Any] | None = None,
-                    renderer: BaseRenderer | None = None,
-                    *,
-                    force: bool = False) -> None:
+def copy_asset_file(
+    source: str | os.PathLike[str],
+    destination: str | os.PathLike[str],
+    context: dict[str, Any] | None = None,
+    renderer: BaseRenderer | None = None,
+    *,
+    force: bool = False,
+) -> None:
     """Copy an asset file to destination.
 
     On copying, it expands the template variables if context argument is given and
@@ -53,44 +57,59 @@ def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLi
     if not os.path.exists(source):
         return
 
-    if os.path.isdir(destination):
+    destination = Path(destination)
+    if destination.is_dir():
         # Use source filename if destination points a directory
-        destination = os.path.join(destination, os.path.basename(source))
-    else:
-        destination = str(destination)
+        destination /= os.path.basename(source)
 
     if _template_basename(source) and context is not None:
         if renderer is None:
             from sphinx.util.template import SphinxRenderer
+
             renderer = SphinxRenderer()
 
         with open(source, encoding='utf-8') as fsrc:
             template_content = fsrc.read()
         rendered_template = renderer.render_string(template_content, context)
 
-        if (
-            not force
-            and os.path.exists(destination)
-            and template_content != rendered_template
-        ):
-            msg = __('Aborted attempted copy from rendered template %s to %s '
-                     '(the destination path has existing data).')
-            logger.warning(msg, os.fsdecode(source), os.fsdecode(destination),
-                           type='misc', subtype='copy_overwrite')
+        if not force and destination.exists() and template_content != rendered_template:
+            msg = __(
+                'Aborted attempted copy from rendered template %s to %s '
+                '(the destination path has existing data).'
+            )
+            logger.warning(
+                msg,
+                os.fsdecode(source),
+                os.fsdecode(destination),
+                type='misc',
+                subtype='copy_overwrite',
+            )
             return
 
         destination = _template_basename(destination) or destination
         with open(destination, 'w', encoding='utf-8') as fdst:
+            msg = __('Writing evaluated template result to %s')
+            logger.info(
+                msg,
+                os.fsdecode(destination),
+                type='misc',
+                subtype='template_evaluation',
+            )
             fdst.write(rendered_template)
     else:
         copyfile(source, destination, force=force)
 
 
-def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[str],
-               excluded: PathMatcher = lambda path: False,
-               context: dict[str, Any] | None = None, renderer: BaseRenderer | None = None,
-               onerror: Callable[[str, Exception], None] | None = None,
-               *, force: bool = False) -> None:
+def copy_asset(
+    source: str | os.PathLike[str],
+    destination: str | os.PathLike[str],
+    excluded: PathMatcher = lambda path: False,
+    context: dict[str, Any] | None = None,
+    renderer: BaseRenderer | None = None,
+    onerror: Callable[[str, Exception], None] | None = None,
+    *,
+    force: bool = False,
+) -> None:
     """Copy asset files to destination recursively.
 
     On copying, it expands the template variables if context argument is given and
@@ -111,14 +130,14 @@ def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[st
 
     if renderer is None:
         from sphinx.util.template import SphinxRenderer
+
         renderer = SphinxRenderer()
 
     ensuredir(destination)
     if os.path.isfile(source):
-        copy_asset_file(source, destination,
-                        context=context,
-                        renderer=renderer,
-                        force=force)
+        copy_asset_file(
+            source, destination, context=context, renderer=renderer, force=force
+        )
         return
 
     for root, dirs, files in os.walk(source, followlinks=True):
@@ -132,11 +151,13 @@ def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[st
         for filename in files:
             if not excluded(posixpath.join(reldir, filename)):
                 try:
-                    copy_asset_file(posixpath.join(root, filename),
-                                    posixpath.join(destination, reldir),
-                                    context=context,
-                                    renderer=renderer,
-                                    force=force)
+                    copy_asset_file(
+                        posixpath.join(root, filename),
+                        posixpath.join(destination, reldir),
+                        context=context,
+                        renderer=renderer,
+                        force=force,
+                    )
                 except Exception as exc:
                     if onerror:
                         onerror(posixpath.join(root, filename), exc)

sphinx/util/http_date.py

@@ -12,7 +12,7 @@ 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')
+               'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec')  # fmt: skip
 _GMT_OFFSET = float(time.localtime().tm_gmtoff)
 
 
@@ -29,18 +29,20 @@ def rfc1123_to_epoch(rfc1123: str) -> float:
     t = parsedate_tz(rfc1123)
     if t is None:
         raise ValueError
-    if not rfc1123.endswith(" GMT"):
+    if not rfc1123.endswith(' GMT'):
         warnings.warn(
-            "HTTP-date string does not meet RFC 7231 requirements "
+            'HTTP-date string does not meet RFC 7231 requirements '
             f"(must end with 'GMT'): {rfc1123!r}",
-            RemovedInSphinx90Warning, stacklevel=3,
+            RemovedInSphinx90Warning,
+            stacklevel=3,
         )
     epoch_secs = time.mktime(time.struct_time(t[:9])) + _GMT_OFFSET
     if (gmt_offset := t[9]) != 0:
         warnings.warn(
-            "HTTP-date string does not meet RFC 7231 requirements "
-            f"(must be GMT time): {rfc1123!r}",
-            RemovedInSphinx90Warning, stacklevel=3,
+            'HTTP-date string does not meet RFC 7231 requirements '
+            f'(must be GMT time): {rfc1123!r}',
+            RemovedInSphinx90Warning,
+            stacklevel=3,
         )
         return epoch_secs - (gmt_offset or 0)
     return epoch_secs

sphinx/util/i18n.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 import re
+import sys
 from datetime import datetime, timezone
 from os import path
 from typing import TYPE_CHECKING, NamedTuple
@@ -59,6 +60,11 @@ if TYPE_CHECKING:
 
     Formatter: TypeAlias = DateFormatter | TimeFormatter | DatetimeFormatter
 
+if sys.version_info[:2] >= (3, 11):
+    from datetime import UTC
+else:
+    UTC = timezone.utc
+
 logger = logging.getLogger(__name__)
 
 
@@ -69,7 +75,6 @@ class LocaleFileInfoBase(NamedTuple):
 
 
 class CatalogInfo(LocaleFileInfoBase):
-
     @property
     def po_file(self) -> str:
         return self.domain + '.po'
@@ -88,8 +93,9 @@ class CatalogInfo(LocaleFileInfoBase):
 
     def is_outdated(self) -> bool:
         return (
-            not path.exists(self.mo_path) or
-            _last_modified_time(self.mo_path) < _last_modified_time(self.po_path))
+            not path.exists(self.mo_path)
+            or _last_modified_time(self.mo_path) < _last_modified_time(self.po_path)
+        )  # fmt: skip
 
     def write_mo(self, locale: str, use_fuzzy: bool = False) -> None:
         with open(self.po_path, encoding=self.charset) as file_po:
@@ -109,8 +115,13 @@ class CatalogInfo(LocaleFileInfoBase):
 class CatalogRepository:
     """A repository for message catalogs."""
 
-    def __init__(self, basedir: str | os.PathLike[str], locale_dirs: list[str],
-                 language: str, encoding: str) -> None:
+    def __init__(
+        self,
+        basedir: str | os.PathLike[str],
+        locale_dirs: list[str],
+        language: str,
+        encoding: str,
+    ) -> None:
         self.basedir = basedir
         self._locale_dirs = locale_dirs
         self.language = language
@@ -199,13 +210,17 @@ date_format_mappings = {
     '%z':  'ZZZ',     # UTC offset in the form ±HHMM[SS[.ffffff]]
                       # (empty string if the object is naive).
     '%%':  '%',
-}
+}  # fmt: skip
 
 date_format_re = re.compile('(%s)' % '|'.join(date_format_mappings))
 
 
-def babel_format_date(date: datetime, format: str, locale: str,
-                      formatter: Formatter = babel.dates.format_date) -> str:
+def babel_format_date(
+    date: datetime,
+    format: str,
+    locale: 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'):
@@ -217,22 +232,37 @@ def babel_format_date(date: datetime, format: str, locale: str,
         # fallback to English
         return formatter(date, format, locale='en')
     except AttributeError:
-        logger.warning(__('Invalid date format. Quote the string by single quote '
-                          'if you want to output it directly: %s'), format)
+        logger.warning(
+            __(
+                'Invalid date format. Quote the string by single quote '
+                'if you want to output it directly: %s'
+            ),
+            format,
+        )
         return format
 
 
 def format_date(
-    format: str, *, date: datetime | None = None, language: str,
+    format: str,
+    *,
+    date: datetime | None = None,
+    language: str,
+    local_time: bool = False,
 ) -> str:
     if date is None:
         # If time is not specified, try to use $SOURCE_DATE_EPOCH variable
         # See https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal
         source_date_epoch = os.getenv('SOURCE_DATE_EPOCH')
         if source_date_epoch is not None:
-            date = datetime.fromtimestamp(float(source_date_epoch), tz=timezone.utc)
+            date = datetime.fromtimestamp(float(source_date_epoch), tz=UTC)
         else:
-            date = datetime.now(tz=timezone.utc).astimezone()
+            date = datetime.now(tz=UTC)
+
+    if local_time:
+        # > If called with tz=None, the system local time zone
+        # > is assumed for the target time zone.
+        # https://docs.python.org/dev/library/datetime.html#datetime.datetime.astimezone
+        date = date.astimezone(tz=None)
 
     result = []
     tokens = date_format_re.split(format)
@@ -251,12 +281,15 @@ def format_date(
             else:
                 function = babel.dates.format_datetime
 
-            result.append(babel_format_date(date, babel_format, locale=language,
-                                            formatter=function))
+            result.append(
+                babel_format_date(
+                    date, babel_format, locale=language, formatter=function
+                )
+            )
         else:
             result.append(token)
 
-    return "".join(result)
+    return ''.join(result)
 
 
 def get_image_filename_for_language(