Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/builders/gettext.py

@@ -2,25 +2,27 @@
 
 from __future__ import annotations
 
+import codecs
 import operator
+import os
+import os.path
 import time
-from codecs import open
 from collections import defaultdict
-from os import getenv, path, walk
+from os import getenv, walk
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING
 from uuid import uuid4
 
 from docutils import nodes
 
 from sphinx import addnodes, package_dir
+from sphinx._cli.util.colour import bold
 from sphinx.builders import Builder
 from sphinx.errors import ThemeError
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import bold
 from sphinx.util.display import status_iterator
-from sphinx.util.i18n import CatalogInfo, docname_to_domain
+from sphinx.util.i18n import 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
@@ -28,16 +30,16 @@ from sphinx.util.tags import Tags
 from sphinx.util.template import SphinxRenderer
 
 if TYPE_CHECKING:
-    import os
     from collections.abc import Iterable, Iterator, Sequence
+    from typing import Any, Literal
 
     from docutils.nodes import Element
 
     from sphinx.application import Sphinx
-    from sphinx.config import Config
+    from sphinx.util.i18n import CatalogInfo
     from sphinx.util.typing import ExtensionMetadata
 
-DEFAULT_TEMPLATE_PATH = Path(package_dir, 'templates', 'gettext')
+DEFAULT_TEMPLATE_PATH = package_dir.joinpath('templates', 'gettext')
 
 logger = logging.getLogger(__name__)
 
@@ -45,6 +47,12 @@ logger = logging.getLogger(__name__)
 class Message:
     """An entry of translatable message."""
 
+    __slots__ = 'text', 'locations', 'uuids'
+
+    text: str
+    locations: list[tuple[str, int]]
+    uuids: list[str]
+
     def __init__(
         self, text: str, locations: list[tuple[str, int]], uuids: list[str]
     ) -> None:
@@ -52,48 +60,60 @@ class Message:
         self.locations = locations
         self.uuids = uuids
 
+    def __repr__(self) -> str:
+        return (
+            'Message('
+            f'text={self.text!r}, locations={self.locations!r}, uuids={self.uuids!r}'
+            ')'
+        )
+
 
 class Catalog:
     """Catalog of translatable messages."""
 
-    def __init__(self) -> None:
-        self.messages: list[str] = []  # retain insertion order
+    __slots__ = ('metadata',)
 
+    def __init__(self) -> None:
         # msgid -> file, line, uid
         self.metadata: dict[str, list[tuple[str, int, str]]] = {}
 
     def add(self, msg: str, origin: Element | MsgOrigin) -> None:
         if not hasattr(origin, 'uid'):
             # Nodes that are replicated like todo don't have a uid,
-            # however i18n is also unnecessary.
+            # however translation is also unnecessary.
             return
-        if msg not in self.metadata:  # faster lookup in hash
-            self.messages.append(msg)
-            self.metadata[msg] = []
-        line = origin.line
-        if line is None:
-            line = -1
-        self.metadata[msg].append((origin.source, line, origin.uid))  # type: ignore[arg-type]
+        msg_metadata = self.metadata.setdefault(msg, [])
+        line = line if (line := origin.line) is not None else -1
+        msg_metadata.append((origin.source or '', line, origin.uid))
 
     def __iter__(self) -> Iterator[Message]:
-        for message in self.messages:
-            positions = sorted({
-                (source, line) for source, line, uuid in self.metadata[message]
-            })
-            uuids = [uuid for source, line, uuid in self.metadata[message]]
-            yield Message(message, positions, uuids)
+        for message, msg_metadata in self.metadata.items():
+            positions = sorted(set(map(operator.itemgetter(0, 1), msg_metadata)))
+            uuids = list(map(operator.itemgetter(2), msg_metadata))
+            yield Message(text=message, locations=positions, uuids=uuids)
+
+    @property
+    def messages(self) -> list[str]:
+        return list(self.metadata)
 
 
 class MsgOrigin:
-    """
-    Origin holder for Catalog message origin.
-    """
+    """Origin holder for Catalog message origin."""
+
+    __slots__ = 'source', 'line', 'uid'
+
+    source: str
+    line: int
+    uid: str
 
     def __init__(self, source: str, line: int) -> None:
         self.source = source
         self.line = line
         self.uid = uuid4().hex
 
+    def __repr__(self) -> str:
+        return f'<MsgOrigin {self.source}:{self.line}; uid={self.uid!r}>'
+
 
 class GettextRenderer(SphinxRenderer):
     def __init__(
@@ -136,9 +156,7 @@ class I18nTags(Tags):
 
 
 class I18nBuilder(Builder):
-    """
-    General i18n builder.
-    """
+    """General i18n builder."""
 
     name = 'i18n'
     versioning_method = 'text'
@@ -146,10 +164,8 @@ class I18nBuilder(Builder):
 
     def init(self) -> None:
         super().init()
-        self.env.set_versioning_method(
-            self.versioning_method, self.env.config.gettext_uuid
-        )
-        self.tags = I18nTags()
+        self.env.set_versioning_method(self.versioning_method, self.config.gettext_uuid)
+        self.tags = self.app.tags = I18nTags()
         self.catalogs: defaultdict[str, Catalog] = defaultdict(Catalog)
 
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
@@ -174,7 +190,7 @@ class I18nBuilder(Builder):
             if not _is_node_in_substitution_definition(node):
                 catalog.add(msg, node)
 
-        if 'index' in self.env.config.gettext_additional_targets:
+        if 'index' in self.config.gettext_additional_targets:
             # Extract translatable messages from index entries.
             for node, entries in traverse_translatable_index(doctree):
                 for entry_type, value, _target_id, _main, _category_key in entries:
@@ -192,20 +208,20 @@ else:
 ctime = time.strftime('%Y-%m-%d %H:%M%z', timestamp)
 
 
-def should_write(filepath: str, new_content: str) -> bool:
-    if not path.exists(filepath):
+def should_write(filepath: Path, new_content: str) -> bool:
+    if not filepath.exists():
         return True
     try:
-        with open(filepath, encoding='utf-8') as oldpot:
+        with codecs.open(str(filepath), encoding='utf-8') as oldpot:
             old_content = oldpot.read()
-            old_header_index = old_content.index('"POT-Creation-Date:')
-            new_header_index = new_content.index('"POT-Creation-Date:')
-            old_body_index = old_content.index('"PO-Revision-Date:')
-            new_body_index = new_content.index('"PO-Revision-Date:')
-            return (
-                old_content[:old_header_index] != new_content[:new_header_index]
-                or new_content[new_body_index:] != old_content[old_body_index:]
-            )
+        old_header_index = old_content.index('"POT-Creation-Date:')
+        new_header_index = new_content.index('"POT-Creation-Date:')
+        old_body_index = old_content.index('"PO-Revision-Date:')
+        new_body_index = new_content.index('"PO-Revision-Date:')
+        return (
+            old_content[:old_header_index] != new_content[:new_header_index]
+            or new_content[new_body_index:] != old_content[old_body_index:]
+        )
     except ValueError:
         pass
 
@@ -222,9 +238,7 @@ def _is_node_in_substitution_definition(node: nodes.Node) -> bool:
 
 
 class MessageCatalogBuilder(I18nBuilder):
-    """
-    Builds gettext-style message catalogs (.pot files).
-    """
+    """Builds gettext-style message catalogs (.pot files)."""
 
     name = 'gettext'
     epilog = __('The message catalogs are in %(outdir)s.')
@@ -237,11 +251,11 @@ class MessageCatalogBuilder(I18nBuilder):
     def _collect_templates(self) -> set[str]:
         template_files = set()
         for template_path in self.config.templates_path:
-            tmpl_abs_path = path.join(self.app.srcdir, template_path)
+            tmpl_abs_path = self.app.srcdir / template_path
             for dirpath, _dirs, files in walk(tmpl_abs_path):
                 for fn in files:
                     if fn.endswith('.html'):
-                        filename = canon_path(path.join(dirpath, fn))
+                        filename = Path(dirpath, fn).as_posix()
                         template_files.add(filename)
         return template_files
 
@@ -257,10 +271,10 @@ class MessageCatalogBuilder(I18nBuilder):
             files, __('reading templates... '), 'purple', len(files), self.app.verbosity
         ):
             try:
-                with open(template, encoding='utf-8') as f:
+                with codecs.open(template, encoding='utf-8') as f:
                     context = f.read()
                 for line, _meth, msg in extract_translations(context):
-                    origin = MsgOrigin(template, line)
+                    origin = MsgOrigin(source=template, line=line)
                     self.catalogs['sphinx'].add(msg, origin)
             except Exception as exc:
                 msg = f'{template}: {exc!r}'
@@ -287,6 +301,7 @@ class MessageCatalogBuilder(I18nBuilder):
             'display_location': self.config.gettext_location,
             'display_uuid': self.config.gettext_uuid,
         }
+        catalog: Catalog
         for textdomain, catalog in status_iterator(
             self.catalogs.items(),
             __('writing message catalogs... '),
@@ -296,7 +311,7 @@ class MessageCatalogBuilder(I18nBuilder):
             operator.itemgetter(0),
         ):
             # noop if config.gettext_compact is set
-            ensuredir(path.join(self.outdir, path.dirname(textdomain)))
+            ensuredir(self.outdir / os.path.dirname(textdomain))
 
             context['messages'] = list(catalog)
             template_path = [
@@ -305,34 +320,39 @@ class MessageCatalogBuilder(I18nBuilder):
             renderer = GettextRenderer(template_path, outdir=self.outdir)
             content = renderer.render('message.pot.jinja', context)
 
-            pofn = path.join(self.outdir, textdomain + '.pot')
+            pofn = self.outdir / f'{textdomain}.pot'
             if should_write(pofn, content):
-                with open(pofn, 'w', encoding='utf-8') as pofile:
+                with codecs.open(str(pofn), 'w', encoding='utf-8') as pofile:
                     pofile.write(content)
 
 
-def _gettext_compact_validator(app: Sphinx, config: Config) -> None:
-    gettext_compact = config.gettext_compact
-    # Convert 0/1 from the command line to ``bool`` types
-    if gettext_compact == '0':
-        config.gettext_compact = False
-    elif gettext_compact == '1':
-        config.gettext_compact = True
-
-
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(MessageCatalogBuilder)
 
-    app.add_config_value('gettext_compact', True, 'gettext', {bool, str})
-    app.add_config_value('gettext_location', True, 'gettext')
-    app.add_config_value('gettext_uuid', False, 'gettext')
-    app.add_config_value('gettext_auto_build', True, 'env')
-    app.add_config_value('gettext_additional_targets', [], 'env', types={set, list})
     app.add_config_value(
-        'gettext_last_translator', 'FULL NAME <EMAIL@ADDRESS>', 'gettext'
+        'gettext_compact', True, 'gettext', types=frozenset({bool, str})
+    )
+    app.add_config_value('gettext_location', True, 'gettext', types=frozenset({bool}))
+    app.add_config_value('gettext_uuid', False, 'gettext', types=frozenset({bool}))
+    app.add_config_value('gettext_auto_build', True, 'env', types=frozenset({bool}))
+    app.add_config_value(
+        'gettext_additional_targets',
+        [],
+        'env',
+        types=frozenset({frozenset, list, set, tuple}),
+    )
+    app.add_config_value(
+        'gettext_last_translator',
+        'FULL NAME <EMAIL@ADDRESS>',
+        'gettext',
+        types=frozenset({str}),
+    )
+    app.add_config_value(
+        'gettext_language_team',
+        'LANGUAGE <LL@li.org>',
+        'gettext',
+        types=frozenset({str}),
     )
-    app.add_config_value('gettext_language_team', 'LANGUAGE <LL@li.org>', 'gettext')
-    app.connect('config-inited', _gettext_compact_validator, priority=800)
 
     return {
         'version': 'builtin',