Sphinx 7.1.1__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/builders/epub3.py

@@ -6,28 +6,30 @@ Originally derived from epub.py.
 from __future__ import annotations
 
 import html
+import os
 import re
+import time
 from os import path
-from typing import Any, NamedTuple
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from sphinx import package_dir
-from sphinx.application import Sphinx
 from sphinx.builders import _epub_base
 from sphinx.config import ENUM, Config
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.fileutil import copy_asset_file
-from sphinx.util.i18n import format_date
 from sphinx.util.osutil import make_filename
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 
 class NavPoint(NamedTuple):
     text: str
     refuri: str
-    children: list[Any]     # mypy does not support recursive types
-                            # https://github.com/python/mypy/issues/7069
+    children: list[NavPoint]
 
 
 # writing modes
@@ -99,12 +101,17 @@ class Epub3Builder(_epub_base.EpubBuilder):
         """
         writing_mode = self.config.epub_writing_mode
 
+        if (source_date_epoch := os.getenv('SOURCE_DATE_EPOCH')) is not None:
+            time_tuple = time.gmtime(int(source_date_epoch))
+        else:
+            time_tuple = time.gmtime()
+
         metadata = super().content_metadata()
         metadata['description'] = html.escape(self.config.epub_description)
         metadata['contributor'] = html.escape(self.config.epub_contributor)
         metadata['page_progression_direction'] = PAGE_PROGRESSION_DIRECTIONS.get(writing_mode)
         metadata['ibook_scroll_axis'] = IBOOK_SCROLL_AXIS.get(writing_mode)
-        metadata['date'] = html.escape(format_date("%Y-%m-%dT%H:%M:%SZ", language='en'))
+        metadata['date'] = html.escape(time.strftime("%Y-%m-%dT%H:%M:%SZ", time_tuple))
         metadata['version'] = html.escape(self.config.version)
         metadata['epub_version'] = self.config.epub_version
         return metadata
@@ -156,7 +163,8 @@ class Epub3Builder(_epub_base.EpubBuilder):
                 navstack[-1].children.append(navpoint)
                 navstack.append(navpoint)
             else:
-                raise RuntimeError('Should never reach here. It might be a bug.')
+                unreachable = 'Should never reach here. It might be a bug.'
+                raise RuntimeError(unreachable)
 
         return navstack[0].children
 
@@ -245,7 +253,7 @@ def convert_epub_css_files(app: Sphinx, config: Config) -> None:
                 logger.warning(__('invalid css_file: %r, ignored'), entry)
                 continue
 
-    config.epub_css_files = epub_css_files  # type: ignore
+    config.epub_css_files = epub_css_files  # type: ignore[attr-defined]
 
 
 def setup(app: Sphinx) -> dict[str, Any]:

sphinx/builders/gettext.py

@@ -2,31 +2,37 @@
 
 from __future__ import annotations
 
+import time
 from codecs import open
 from collections import defaultdict
-from datetime import datetime, timedelta, timezone, tzinfo
 from os import getenv, path, walk
-from time import time
-from typing import Any, Generator, Iterable
+from typing import TYPE_CHECKING, Any
 from uuid import uuid4
 
 from docutils import nodes
-from docutils.nodes import Element
 
 from sphinx import addnodes, package_dir
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.errors import ThemeError
 from sphinx.locale import __
-from sphinx.util import logging, split_index_msg
-from sphinx.util.console import bold  # type: ignore
+from sphinx.util import logging
+from sphinx.util.console import bold  # type: ignore[attr-defined]
 from sphinx.util.display import status_iterator
 from sphinx.util.i18n import CatalogInfo, docname_to_domain
+from sphinx.util.index_entries import split_index_msg
 from sphinx.util.nodes import extract_messages, traverse_translatable_index
 from sphinx.util.osutil import canon_path, ensuredir, relpath
 from sphinx.util.tags import Tags
 from sphinx.util.template import SphinxRenderer
 
+if TYPE_CHECKING:
+    import os
+    from collections.abc import Generator, Iterable
+
+    from docutils.nodes import Element
+
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 
@@ -81,11 +87,12 @@ class MsgOrigin:
 
 class GettextRenderer(SphinxRenderer):
     def __init__(
-        self, template_path: str | None = None, outdir: str | None = None,
+        self, template_path: list[str | os.PathLike[str]] | None = None,
+            outdir: str | os.PathLike[str] | None = None,
     ) -> None:
         self.outdir = outdir
         if template_path is None:
-            template_path = path.join(package_dir, 'templates', 'gettext')
+            template_path = [path.join(package_dir, 'templates', 'gettext')]
         super().__init__(template_path)
 
         def escape(s: str) -> str:
@@ -147,11 +154,13 @@ class I18nBuilder(Builder):
 
         for toctree in self.env.tocs[docname].findall(addnodes.toctree):
             for node, msg in extract_messages(toctree):
-                node.uid = ''  # type: ignore  # Hack UUID model
+                node.uid = ''  # type: ignore[attr-defined]  # Hack UUID model
                 catalog.add(msg, node)
 
         for node, msg in extract_messages(doctree):
-            catalog.add(msg, node)
+            # Do not extract messages from within substitution definitions.
+            if not _is_node_in_substitution_definition(node):
+                catalog.add(msg, node)
 
         if 'index' in self.env.config.gettext_additional_targets:
             # Extract translatable messages from index entries.
@@ -161,36 +170,14 @@ class I18nBuilder(Builder):
                         catalog.add(m, node)
 
 
-# determine tzoffset once to remain unaffected by DST change during build
-timestamp = time()
-local_time = datetime.fromtimestamp(timestamp)
-utc_time = datetime.fromtimestamp(timestamp, tz=timezone.utc)
-tzdelta = local_time - utc_time.replace(tzinfo=None)
-
-# set timestamp from SOURCE_DATE_EPOCH if set
-# see https://reproducible-builds.org/specs/source-date-epoch/
-source_date_epoch = getenv('SOURCE_DATE_EPOCH')
-if source_date_epoch is not None:
-    timestamp = float(source_date_epoch)
-    tzdelta = timedelta(0)
-
-
-class LocalTimeZone(tzinfo):
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super().__init__(*args, **kwargs)
-        self.tzdelta = tzdelta
-
-    def tzname(self, dt: datetime | None) -> str:  # purely to satisfy mypy
-        return "local"
-
-    def utcoffset(self, dt: datetime | None) -> timedelta:
-        return self.tzdelta
-
-    def dst(self, dt: datetime | None) -> timedelta:
-        return timedelta(0)
-
-
-ltz = LocalTimeZone()
+# If set, use the timestamp from SOURCE_DATE_EPOCH
+# https://reproducible-builds.org/specs/source-date-epoch/
+if (source_date_epoch := getenv('SOURCE_DATE_EPOCH')) is not None:
+    timestamp = time.gmtime(float(source_date_epoch))
+else:
+    # determine timestamp once to remain unaffected by DST changes during build
+    timestamp = time.localtime()
+ctime = time.strftime('%Y-%m-%d %H:%M%z', timestamp)
 
 
 def should_write(filepath: str, new_content: str) -> bool:
@@ -211,6 +198,15 @@ def should_write(filepath: str, new_content: str) -> bool:
     return True
 
 
+def _is_node_in_substitution_definition(node: nodes.Node) -> bool:
+    """Check "node" to test if it is in a substitution definition."""
+    while node.parent:
+        if isinstance(node, nodes.substitution_definition):
+            return True
+        node = node.parent
+    return False
+
+
 class MessageCatalogBuilder(I18nBuilder):
     """
     Builds gettext-style message catalogs (.pot files).
@@ -251,7 +247,8 @@ class MessageCatalogBuilder(I18nBuilder):
                     origin = MsgOrigin(template, line)
                     self.catalogs['sphinx'].add(msg, origin)
             except Exception as exc:
-                raise ThemeError(f'{template}: {exc!r}') from exc
+                msg = f'{template}: {exc!r}'
+                raise ThemeError(msg) from exc
 
     def build(
         self,
@@ -270,7 +267,7 @@ class MessageCatalogBuilder(I18nBuilder):
             'project': self.config.project,
             'last_translator': self.config.gettext_last_translator,
             'language_team': self.config.gettext_language_team,
-            'ctime': datetime.fromtimestamp(timestamp, ltz).strftime('%Y-%m-%d %H:%M%z'),
+            'ctime': ctime,
             'display_location': self.config.gettext_location,
             'display_uuid': self.config.gettext_uuid,
         }