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

sphinx/builders/html/_assets.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import os
+import zlib
+from typing import TYPE_CHECKING
+
+from sphinx.errors import ThemeError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class _CascadingStyleSheet:
+    filename: str | os.PathLike[str]
+    priority: int
+    attributes: dict[str, str]
+
+    def __init__(
+        self,
+        filename: str | os.PathLike[str], /, *,
+        priority: int = 500,
+        rel: str = 'stylesheet',
+        type: str = 'text/css',
+        **attributes: str,
+    ) -> None:
+        object.__setattr__(self, 'filename', filename)
+        object.__setattr__(self, 'priority', priority)
+        object.__setattr__(self, 'attributes', {'rel': rel, 'type': type, **attributes})
+
+    def __str__(self):
+        attr = ', '.join(f'{k}={v!r}' for k, v in self.attributes.items())
+        return (f'{self.__class__.__name__}({self.filename!r}, '
+                f'priority={self.priority}, '
+                f'{attr})')
+
+    def __eq__(self, other):
+        if not isinstance(other, _CascadingStyleSheet):
+            return NotImplemented
+        return (self.filename == other.filename
+                and self.priority == other.priority
+                and self.attributes == other.attributes)
+
+    def __hash__(self):
+        return hash((self.filename, self.priority, *sorted(self.attributes.items())))
+
+    def __setattr__(self, key, value):
+        msg = f'{self.__class__.__name__} is immutable'
+        raise AttributeError(msg)
+
+    def __delattr__(self, key):
+        msg = f'{self.__class__.__name__} is immutable'
+        raise AttributeError(msg)
+
+
+class _JavaScript:
+    filename: str | os.PathLike[str]
+    priority: int
+    attributes: dict[str, str]
+
+    def __init__(
+        self,
+        filename: str | os.PathLike[str], /, *,
+        priority: int = 500,
+        **attributes: str,
+    ) -> None:
+        object.__setattr__(self, 'filename', filename)
+        object.__setattr__(self, 'priority', priority)
+        object.__setattr__(self, 'attributes', attributes)
+
+    def __str__(self):
+        attr = ''
+        if self.attributes:
+            attr = ', ' + ', '.join(f'{k}={v!r}' for k, v in self.attributes.items())
+        return (f'{self.__class__.__name__}({self.filename!r}, '
+                f'priority={self.priority}'
+                f'{attr})')
+
+    def __eq__(self, other):
+        if not isinstance(other, _JavaScript):
+            return NotImplemented
+        return (self.filename == other.filename
+                and self.priority == other.priority
+                and self.attributes == other.attributes)
+
+    def __hash__(self):
+        return hash((self.filename, self.priority, *sorted(self.attributes.items())))
+
+    def __setattr__(self, key, value):
+        msg = f'{self.__class__.__name__} is immutable'
+        raise AttributeError(msg)
+
+    def __delattr__(self, key):
+        msg = f'{self.__class__.__name__} is immutable'
+        raise AttributeError(msg)
+
+
+def _file_checksum(outdir: Path, filename: str | os.PathLike[str]) -> str:
+    filename = os.fspath(filename)
+    # Don't generate checksums for HTTP URIs
+    if '://' in filename:
+        return ''
+    # Some themes and extensions have used query strings
+    # for a similar asset checksum feature.
+    # As we cannot safely strip the query string,
+    # raise an error to the user.
+    if '?' in filename:
+        msg = f'Local asset file paths must not contain query strings: {filename!r}'
+        raise ThemeError(msg)
+    try:
+        # Remove all carriage returns to avoid checksum differences
+        content = outdir.joinpath(filename).read_bytes().translate(None, b'\r')
+    except FileNotFoundError:
+        return ''
+    if not content:
+        return ''
+    return f'{zlib.crc32(content):08x}'

sphinx/builders/html/transforms.py

@@ -3,14 +3,16 @@
 from __future__ import annotations
 
 import re
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
 
-from sphinx.application import Sphinx
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util.nodes import NodeMatcher
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
 
 class KeyboardTransform(SphinxPostTransform):
     """Transform :kbd: role to more detailed form.

sphinx/builders/latex/__init__.py

@@ -5,14 +5,12 @@ from __future__ import annotations
 import os
 import warnings
 from os import path
-from typing import Any, Iterable
+from typing import TYPE_CHECKING, Any
 
 from docutils.frontend import OptionParser
-from docutils.nodes import Node
 
 import sphinx.builders.latex.nodes  # noqa: F401,E501  # Workaround: import this before writer to avoid ImportError
 from sphinx import addnodes, highlighting, package_dir
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.builders.latex.constants import ADDITIONAL_SETTINGS, DEFAULT_SETTINGS, SHORTHANDOFF
 from sphinx.builders.latex.theming import Theme, ThemeFactory
@@ -22,7 +20,7 @@ from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import NoUri, SphinxError
 from sphinx.locale import _, __
 from sphinx.util import logging, texescape
-from sphinx.util.console import bold, darkgreen  # type: ignore
+from sphinx.util.console import bold, darkgreen  # type: ignore[attr-defined]
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import SphinxFileOutput, new_document
 from sphinx.util.fileutil import copy_asset_file
@@ -35,6 +33,13 @@ from sphinx.writers.latex import LaTeXTranslator, LaTeXWriter
 # load docutils.nodes after loading sphinx.builders.latex.nodes
 from docutils import nodes  # isort:skip
 
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+
 XINDY_LANG_OPTIONS = {
     # language codes from docutils.writers.latex2e.Babel
     # ! xindy language names may differ from those in use by LaTeX/babel
@@ -116,7 +121,7 @@ class LaTeXBuilder(Builder):
     default_translator_class = LaTeXTranslator
 
     def init(self) -> None:
-        self.babel: ExtBabel = None
+        self.babel: ExtBabel
         self.context: dict[str, Any] = {}
         self.docnames: Iterable[str] = {}
         self.document_data: list[tuple[str, str, str, str, str, bool]] = []
@@ -153,7 +158,7 @@ class LaTeXBuilder(Builder):
                 logger.warning(__('"latex_documents" config value references unknown '
                                   'document %s'), docname)
                 continue
-            self.document_data.append(entry)  # type: ignore
+            self.document_data.append(entry)  # type: ignore[arg-type]
             if docname.endswith(SEP + 'index'):
                 docname = docname[:-5]
             self.titles.append((docname, entry[2]))
@@ -314,7 +319,7 @@ class LaTeXBuilder(Builder):
 
     def get_contentsname(self, indexfile: str) -> str:
         tree = self.env.get_doctree(indexfile)
-        contentsname = None
+        contentsname = ''
         for toctree in tree.findall(addnodes.toctree):
             if 'caption' in toctree:
                 contentsname = toctree['caption']

sphinx/builders/latex/theming.py

@@ -4,13 +4,16 @@ from __future__ import annotations
 
 import configparser
 from os import path
+from typing import TYPE_CHECKING
 
-from sphinx.application import Sphinx
-from sphinx.config import Config
 from sphinx.errors import ThemeError
 from sphinx.locale import __
 from sphinx.util import logging
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
 logger = logging.getLogger(__name__)
 
 

sphinx/builders/latex/transforms.py

@@ -2,14 +2,12 @@
 
 from __future__ import annotations
 
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Element, Node
 from docutils.transforms.references import Substitutions
 
 from sphinx import addnodes
-from sphinx.application import Sphinx
 from sphinx.builders.latex.nodes import (
     captioned_literal_block,
     footnotemark,
@@ -23,6 +21,11 @@ from sphinx.transforms import SphinxTransform
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util.nodes import NodeMatcher
 
+if TYPE_CHECKING:
+    from docutils.nodes import Element, Node
+
+    from sphinx.application import Sphinx
+
 URI_SCHEMES = ('mailto:', 'http:', 'https:', 'ftp:')
 
 

sphinx/builders/linkcheck.py

@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
+import contextlib
 import json
 import re
 import socket
 import time
-from datetime import datetime, timezone
-from email.utils import parsedate_to_datetime
+from email.utils import parsedate_tz
 from html.parser import HTMLParser
 from os import path
 from queue import PriorityQueue, Queue
@@ -22,11 +22,18 @@ from sphinx.builders.dummy import DummyBuilder
 from sphinx.locale import __
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import encode_uri, logging, requests
-from sphinx.util.console import darkgray, darkgreen, purple, red, turquoise  # type: ignore
+from sphinx.util.console import (  # type: ignore[attr-defined]
+    darkgray,
+    darkgreen,
+    purple,
+    red,
+    turquoise,
+)
 from sphinx.util.nodes import get_node_line
 
 if TYPE_CHECKING:
-    from typing import Any, Callable, Generator, Iterator
+    from collections.abc import Generator, Iterator
+    from typing import Any, Callable
 
     from requests import Response
 
@@ -65,7 +72,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
 
         output_text = path.join(self.outdir, 'output.txt')
         output_json = path.join(self.outdir, 'output.json')
-        with open(output_text, 'w', encoding='utf-8') as self.txt_outfile,\
+        with open(output_text, 'w', encoding='utf-8') as self.txt_outfile, \
              open(output_json, 'w', encoding='utf-8') as self.json_outfile:
             for result in checker.check(self.hyperlinks):
                 self.process_result(result)
@@ -298,14 +305,12 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                 break
 
             netloc = urlsplit(uri).netloc
-            try:
+            with contextlib.suppress(KeyError):
                 # Refresh rate limit.
                 # When there are many links in the queue, workers are all stuck waiting
                 # for responses, but the builder keeps queuing. Links in the queue may
                 # have been queued before rate limits were discovered.
                 next_check = self.rate_limits[netloc].next_check
-            except KeyError:
-                pass
             if next_check > time.time():
                 # Sleep before putting message back in the queue to avoid
                 # waking up other threads.
@@ -406,7 +411,8 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                     _user_agent=self.user_agent,
                     _tls_info=(self.tls_verify, self.tls_cacerts),
                 ) as response:
-                    if response.ok and anchor and not contains_anchor(response, anchor):
+                    if (self.check_anchors and response.ok and anchor
+                            and not contains_anchor(response, anchor)):
                         raise Exception(__(f'Anchor {anchor!r} not found'))
 
                 # Copy data we need from the (closed) response
@@ -482,14 +488,16 @@ class HyperlinkAvailabilityCheckWorker(Thread):
             except ValueError:
                 try:
                     # An HTTP-date: time of next attempt.
-                    until = parsedate_to_datetime(retry_after)
-                except (TypeError, ValueError):
+                    parsed = parsedate_tz(retry_after)
+                    assert parsed is not None
+                    # the 10th element is the GMT offset in seconds
+                    next_check = time.mktime(parsed[:9]) - (parsed[9] or 0)
+                except (AssertionError, TypeError, ValueError):
                     # TypeError: Invalid date format.
                     # ValueError: Invalid date, e.g. Oct 52th.
                     pass
                 else:
-                    next_check = datetime.timestamp(until)
-                    delay = (until - datetime.now(timezone.utc)).total_seconds()
+                    delay = next_check - time.time()
             else:
                 next_check = time.time() + delay
         netloc = urlsplit(response_url).netloc

sphinx/builders/manpage.py

@@ -4,23 +4,25 @@ from __future__ import annotations
 
 import warnings
 from os import path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from docutils.frontend import OptionParser
 from docutils.io import FileOutput
 
 from sphinx import addnodes
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
-from sphinx.config import Config
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen  # type: ignore
+from sphinx.util.console import darkgreen  # type: ignore[attr-defined]
 from sphinx.util.display import progress_message
 from sphinx.util.nodes import inline_all_toctrees
 from sphinx.util.osutil import ensuredir, make_filename_from_project
 from sphinx.writers.manpage import ManualPageTranslator, ManualPageWriter
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
 logger = logging.getLogger(__name__)
 
 

sphinx/builders/singlehtml.py

@@ -3,20 +3,23 @@
 from __future__ import annotations
 
 from os import path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
-from docutils.nodes import Node
 
-from sphinx.application import Sphinx
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.environment.adapters.toctree import TocTree
+from sphinx.environment.adapters.toctree import global_toctree_for_doc
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen  # type: ignore
+from sphinx.util.console import darkgreen  # type: ignore[attr-defined]
 from sphinx.util.display import progress_message
 from sphinx.util.nodes import inline_all_toctrees
 
+if TYPE_CHECKING:
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,9 +64,13 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
                 refnode['refuri'] = fname + refuri[hashindex:]
 
     def _get_local_toctree(self, docname: str, collapse: bool = True, **kwargs: Any) -> str:
-        if 'includehidden' not in kwargs:
+        if kwargs.get('includehidden', 'false').lower() == 'false':
             kwargs['includehidden'] = False
-        toctree = TocTree(self.env).get_toctree_for(docname, self, collapse, **kwargs)
+        elif kwargs['includehidden'].lower() == 'true':
+            kwargs['includehidden'] = True
+        if kwargs.get('maxdepth') == '':
+            kwargs.pop('maxdepth')
+        toctree = global_toctree_for_doc(self.env, docname, self, collapse=collapse, **kwargs)
         if toctree is not None:
             self.fix_refuris(toctree)
         return self.render_partial(toctree)['fragment']
@@ -118,7 +125,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
 
     def get_doc_context(self, docname: str, body: str, metatags: str) -> dict[str, Any]:
         # no relation links...
-        toctree = TocTree(self.env).get_toctree_for(self.config.root_doc, self, False)
+        toctree = global_toctree_for_doc(self.env, self.config.root_doc, self, collapse=False)
         # if there is no toctree, toc is None
         if toctree:
             self.fix_refuris(toctree)
@@ -146,7 +153,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         docnames = self.env.all_docs
 
         with progress_message(__('preparing documents')):
-            self.prepare_writing(docnames)  # type: ignore
+            self.prepare_writing(docnames)  # type: ignore[arg-type]
 
         with progress_message(__('assembling single document')):
             doctree = self.assemble_doctree()

sphinx/builders/texinfo.py

@@ -5,22 +5,19 @@ from __future__ import annotations
 import os
 import warnings
 from os import path
-from typing import Any, Iterable
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
 from docutils.frontend import OptionParser
 from docutils.io import FileOutput
-from docutils.nodes import Node
 
 from sphinx import addnodes, package_dir
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
-from sphinx.config import Config
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import NoUri
 from sphinx.locale import _, __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen  # type: ignore
+from sphinx.util.console import darkgreen  # type: ignore[attr-defined]
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import new_document
 from sphinx.util.fileutil import copy_asset_file
@@ -28,6 +25,14 @@ from sphinx.util.nodes import inline_all_toctrees
 from sphinx.util.osutil import SEP, ensuredir, make_filename_from_project
 from sphinx.writers.texinfo import TexinfoTranslator, TexinfoWriter
 
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
 logger = logging.getLogger(__name__)
 template_dir = os.path.join(package_dir, 'templates', 'texinfo')
 
@@ -78,7 +83,7 @@ class TexinfoBuilder(Builder):
                 logger.warning(__('"texinfo_documents" config value references unknown '
                                   'document %s'), docname)
                 continue
-            self.document_data.append(entry)  # type: ignore
+            self.document_data.append(entry)  # type: ignore[arg-type]
             if docname.endswith(SEP + 'index'):
                 docname = docname[:-5]
             self.titles.append((docname, entry[2]))

sphinx/builders/text.py

@@ -3,18 +3,23 @@
 from __future__ import annotations
 
 from os import path
-from typing import Any, Iterator
+from typing import TYPE_CHECKING, Any
 
 from docutils.io import StringOutput
-from docutils.nodes import Node
 
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.osutil import ensuredir, os_path
 from sphinx.writers.text import TextTranslator, TextWriter
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 

sphinx/builders/xml.py

@@ -3,20 +3,25 @@
 from __future__ import annotations
 
 from os import path
-from typing import Any, Iterator
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
 from docutils.io import StringOutput
-from docutils.nodes import Node
 from docutils.writers.docutils_xml import XMLTranslator
 
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.osutil import ensuredir, os_path
 from sphinx.writers.xml import PseudoXMLWriter, XMLWriter
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 
@@ -68,7 +73,7 @@ class XMLBuilder(Builder):
         doctree = doctree.deepcopy()
         for domain in self.env.domains.values():
             xmlns = "xmlns:" + domain.name
-            doctree[xmlns] = "https://www.sphinx-doc.org/"  # type: ignore
+            doctree[xmlns] = "https://www.sphinx-doc.org/"  # type: ignore[index]
         for node in doctree.findall(nodes.Element):
             for att, value in node.attributes.items():
                 if isinstance(value, tuple):

sphinx/cmd/build.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import bdb
+import contextlib
 import locale
 import multiprocessing
 import os
@@ -11,7 +12,7 @@ import pdb  # NoQA: T100
 import sys
 import traceback
 from os import path
-from typing import Any, TextIO
+from typing import TYPE_CHECKING, Any, TextIO
 
 from docutils.utils import SystemMessage
 
@@ -21,10 +22,18 @@ from sphinx.application import Sphinx
 from sphinx.errors import SphinxError, SphinxParallelError
 from sphinx.locale import __
 from sphinx.util import Tee
-from sphinx.util.console import color_terminal, nocolor, red, terminal_safe  # type: ignore
+from sphinx.util.console import (  # type: ignore[attr-defined]
+    color_terminal,
+    nocolor,
+    red,
+    terminal_safe,
+)
 from sphinx.util.docutils import docutils_namespace, patch_docutils
 from sphinx.util.exceptions import format_exception_cut_frames, save_traceback
-from sphinx.util.osutil import abspath, ensuredir
+from sphinx.util.osutil import ensuredir
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
 
 
 def handle_exception(
@@ -198,13 +207,13 @@ files can be built by specifying individual filenames.
     return parser
 
 
-def make_main(argv: list[str] = sys.argv[1:]) -> int:
+def make_main(argv: Sequence[str]) -> int:
     """Sphinx build "make mode" entry."""
     from sphinx.cmd import make_mode
     return make_mode.run_make_mode(argv[1:])
 
 
-def _parse_arguments(argv: list[str] = sys.argv[1:]) -> argparse.Namespace:
+def _parse_arguments(argv: Sequence[str]) -> argparse.Namespace:
     parser = get_parser()
     args = parser.parse_args(argv)
 
@@ -234,13 +243,13 @@ def _parse_arguments(argv: list[str] = sys.argv[1:]) -> argparse.Namespace:
 
     if warning and args.warnfile:
         try:
-            warnfile = abspath(args.warnfile)
+            warnfile = path.abspath(args.warnfile)
             ensuredir(path.dirname(warnfile))
-            warnfp = open(args.warnfile, 'w', encoding="utf-8")
+            warnfp = open(args.warnfile, 'w', encoding="utf-8")  # NoQA: SIM115
         except Exception as exc:
             parser.error(__('cannot open warning file %r: %s') % (
                 args.warnfile, exc))
-        warning = Tee(warning, warnfp)  # type: ignore
+        warning = Tee(warning, warnfp)  # type: ignore[assignment]
         error = warning
 
     args.status = status
@@ -260,10 +269,9 @@ def _parse_arguments(argv: list[str] = sys.argv[1:]) -> argparse.Namespace:
             key, val = val.split('=')
         except ValueError:
             parser.error(__('-A option argument must be in the form name=value'))
-        try:
+        with contextlib.suppress(ValueError):
             val = int(val)
-        except ValueError:
-            pass
+
         confoverrides['html_context.%s' % key] = val
 
     if args.nitpicky:
@@ -274,7 +282,7 @@ def _parse_arguments(argv: list[str] = sys.argv[1:]) -> argparse.Namespace:
     return args
 
 
-def build_main(argv: list[str] = sys.argv[1:]) -> int:
+def build_main(argv: Sequence[str]) -> int:
     """Sphinx build "main" command-line entry."""
     args = _parse_arguments(argv)
 
@@ -314,17 +322,22 @@ def _bug_report_info() -> int:
     return 0
 
 
-def main(argv: list[str] = sys.argv[1:]) -> int:
+def main(argv: Sequence[str] = (), /) -> int:
     locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console()
 
+    if not argv:
+        argv = sys.argv[1:]
+
     if argv[:1] == ['--bug-report']:
         return _bug_report_info()
     if argv[:1] == ['-M']:
         return make_main(argv)
+    elif argv[:1] == ['build']:
+        return build_main(argv[1:])
     else:
         return build_main(argv)
 
 
 if __name__ == '__main__':
-    raise SystemExit(main())
+    raise SystemExit(main(sys.argv[1:]))