Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__py3-none-any.whl

sphinx/search/__init__.py

@@ -6,27 +6,44 @@ import dataclasses
 import functools
 import html
 import json
+import os
 import pickle
 import re
 from importlib import import_module
-from os import path
-from typing import IO, TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
-from docutils.nodes import Element, Node
+from docutils.nodes import Element
 
 from sphinx import addnodes, package_dir
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.index_entries import split_index_msg
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable
+    from typing import Any, Protocol, TypeVar
+
+    from docutils.nodes import Node
 
     from sphinx.environment import BuildEnvironment
 
+    _T_co = TypeVar('_T_co', covariant=True)
+    _T_contra = TypeVar('_T_contra', contravariant=True)
+
+    class _ReadableStream(Protocol[_T_co]):
+        def read(self, n: int = ..., /) -> _T_co: ...
+        def readline(self, n: int = ..., /) -> _T_co: ...
+
+    class _WritableStream(Protocol[_T_contra]):
+        def write(self, s: _T_contra, /) -> object: ...
+
+
+_NON_MINIFIED_JS_PATH = package_dir.joinpath('search', 'non-minified-js')
+_MINIFIED_JS_PATH = package_dir.joinpath('search', 'minified-js')
+
 
 class SearchLanguage:
-    """
-    This class is the base class for search natural language preprocessors.  If
+    """This class is the base class for search natural language preprocessors.  If
     you want to add support for a new language, you should override the methods
     of this class.
 
@@ -78,21 +95,17 @@ var Stemmer = function() {
         self.init(options)
 
     def init(self, options: dict[str, str]) -> None:
-        """
-        Initialize the class with the options the user has given.
-        """
+        """Initialize the class with the options the user has given."""
 
     def split(self, input: str) -> list[str]:
-        """
-        This method splits a sentence into words.  Default splitter splits input
+        """This method splits a sentence into words.  Default splitter splits input
         at white spaces, which should be enough for most languages except CJK
         languages.
         """
         return self._word_re.findall(input)
 
     def stem(self, word: str) -> str:
-        """
-        This method implements stemming algorithm of the Python version.
+        """This method implements stemming algorithm of the Python version.
 
         Default implementation does nothing.  You should implement this if the
         language has any stemming rules.
@@ -104,8 +117,7 @@ var Stemmer = function() {
         return word
 
     def word_filter(self, word: str) -> bool:
-        """
-        Return true if the target word should be registered in the search index.
+        """Return true if the target word should be registered in the search index.
         This method is called after stemming.
         """
         return len(word) == 0 or not (
@@ -119,8 +131,7 @@ from sphinx.search.en import SearchEnglish  # NoQA: E402
 
 
 def parse_stop_word(source: str) -> set[str]:
-    """
-    Parse snowball style word list like this:
+    """Parse snowball style word list like this:
 
     * https://snowball.tartarus.org/algorithms/finnish/stop.txt
     """
@@ -154,8 +165,7 @@ languages: dict[str, str | type[SearchLanguage]] = {
 
 
 class _JavaScriptIndex:
-    """
-    The search index as JavaScript file that calls a function
+    """The search index as JavaScript file that calls a function
     on the documentation search object to register the index.
     """
 
@@ -163,7 +173,8 @@ class _JavaScriptIndex:
     SUFFIX = ')'
 
     def dumps(self, data: Any) -> str:
-        return self.PREFIX + json.dumps(data, sort_keys=True) + self.SUFFIX
+        data_json = json.dumps(data, separators=(',', ':'), sort_keys=True)
+        return self.PREFIX + data_json + self.SUFFIX
 
     def loads(self, s: str) -> Any:
         data = s[len(self.PREFIX) : -len(self.SUFFIX)]
@@ -172,10 +183,10 @@ class _JavaScriptIndex:
             raise ValueError(msg)
         return json.loads(data)
 
-    def dump(self, data: Any, f: IO[str]) -> None:
+    def dump(self, data: Any, f: _WritableStream[str]) -> None:
         f.write(self.dumps(data))
 
-    def load(self, f: IO[str]) -> Any:
+    def load(self, f: _ReadableStream[str]) -> Any:
         return self.loads(f.read())
 
 
@@ -203,20 +214,21 @@ class WordStore:
 
 
 class WordCollector(nodes.NodeVisitor):
-    """
-    A special visitor that collects words for the `IndexBuilder`.
-    """
+    """A special visitor that collects words for the `IndexBuilder`."""
 
     def __init__(self, document: nodes.document, lang: SearchLanguage) -> None:
         super().__init__(document)
         self.found_words: list[str] = []
-        self.found_titles: list[tuple[str, str]] = []
+        self.found_titles: list[tuple[str, str | None]] = []
         self.found_title_words: list[str] = []
         self.lang = lang
 
     def dispatch_visit(self, node: Node) -> None:
         if isinstance(node, nodes.comment):
             raise nodes.SkipNode
+        elif isinstance(node, nodes.Element) and 'no-search' in node['classes']:
+            # skip nodes marked with a 'no-search' class
+            raise nodes.SkipNode
         elif isinstance(node, nodes.raw):
             if 'html' in node.get('format', '').split():
                 # Some people might put content in raw HTML that should be searched,
@@ -241,8 +253,10 @@ class WordCollector(nodes.NodeVisitor):
             self.found_words.extend(self.lang.split(node.astext()))
         elif isinstance(node, nodes.title):
             title = node.astext()
-            ids = node.parent['ids']
-            self.found_titles.append((title, ids[0] if ids else None))
+            if ids := node.parent['ids']:
+                self.found_titles.append((title, ids[0]))
+            else:
+                self.found_titles.append((title, None))
             self.found_title_words.extend(self.lang.split(title))
         elif isinstance(node, Element) and _is_meta_keywords(node, self.lang.lang):  # type: ignore[arg-type]
             keywords = node['content']
@@ -251,8 +265,7 @@ class WordCollector(nodes.NodeVisitor):
 
 
 class IndexBuilder:
-    """
-    Helper class that creates a search index based on the doctrees
+    """Helper class that creates a search index based on the doctrees
     passed to the `feed` method.
     """
 
@@ -264,7 +277,8 @@ class IndexBuilder:
     def __init__(
         self, env: BuildEnvironment, lang: str, options: dict[str, str], scoring: str
     ) -> None:
-        self.env = env
+        self._domains = env.domains
+        self._env_version = env.version
         # docname -> title
         self._titles: dict[str, str | None] = env._search_index_titles
         # docname -> filename
@@ -309,13 +323,16 @@ class IndexBuilder:
             self.js_scorer_code = ''
         self.js_splitter_code = ''
 
-    def load(self, stream: IO, format: Any) -> None:
+    def load(self, stream: _ReadableStream[str | bytes], format: Any) -> None:
         """Reconstruct from frozen data."""
         if isinstance(format, str):
             format = self.formats[format]
         frozen = format.load(stream)
         # if an old index is present, we treat it as not existing.
-        if not isinstance(frozen, dict) or frozen.get('envversion') != self.env.version:
+        if (
+            not isinstance(frozen, dict)
+            or frozen.get('envversion') != self._env_version
+        ):
             msg = 'old format'
             raise ValueError(msg)
         index2fn = frozen['docnames']
@@ -342,7 +359,9 @@ class IndexBuilder:
         self._title_mapping = load_terms(frozen['titleterms'])
         # no need to load keywords/objtypes
 
-    def dump(self, stream: IO, format: Any) -> None:
+    def dump(
+        self, stream: _WritableStream[str] | _WritableStream[bytes], format: Any
+    ) -> None:
         """Dump the frozen index to a stream."""
         if isinstance(format, str):
             format = self.formats[format]
@@ -354,7 +373,7 @@ class IndexBuilder:
         rv: dict[str, list[tuple[int, int, int, str, str]]] = {}
         otypes = self._objtypes
         onames = self._objnames
-        for domain in self.env.domains.sorted():
+        for domain in self._domains.sorted():
             sorted_objects = sorted(domain.get_objects())
             for fullname, dispname, type, docname, anchor, prio in sorted_objects:
                 if docname not in fn2index:
@@ -392,12 +411,12 @@ class IndexBuilder:
     def get_terms(
         self, fn2index: dict[str, int]
     ) -> tuple[dict[str, list[int] | int], dict[str, list[int] | int]]:
-        """
-        Return a mapping of document and title terms to their corresponding sorted document IDs.
+        """Return a mapping of document and title terms to sorted document IDs.
 
-        When a term is only found within a single document, then the value for that term will be
-        an integer value.  When a term is found within multiple documents, the value will be a list
-        of integers.
+        When a term is only found within a single document,
+        then the value for that term will be an integer value.
+        When a term is found within multiple documents,
+        the value will be a list of integers.
         """
         rvs: tuple[dict[str, list[int] | int], dict[str, list[int] | int]] = ({}, {})
         for rv, mapping in zip(rvs, (self._mapping, self._title_mapping), strict=True):
@@ -444,7 +463,7 @@ class IndexBuilder:
             'objtypes': objtypes,
             'objnames': objnames,
             'titleterms': title_terms,
-            'envversion': self.env.version,
+            'envversion': self._env_version,
             'alltitles': alltitles,
             'indexentries': index_entries,
         }
@@ -471,11 +490,15 @@ class IndexBuilder:
             wordnames.intersection_update(docnames)
 
     def feed(
-        self, docname: str, filename: str, title: str, doctree: nodes.document
+        self,
+        docname: str,
+        filename: str | os.PathLike[str],
+        title: str,
+        doctree: nodes.document,
     ) -> None:
         """Feed a doctree to the index."""
         self._titles[docname] = title
-        self._filenames[docname] = filename
+        self._filenames[docname] = os.fspath(filename)
 
         word_store = self._word_collector(doctree)
 
@@ -546,12 +569,12 @@ class IndexBuilder:
             'search_word_splitter_code': js_splitter_code,
         }
 
-    def get_js_stemmer_rawcodes(self) -> list[str]:
+    def get_js_stemmer_rawcodes(self) -> list[_StrPath]:
         """Returns a list of non-minified stemmer JS files to copy."""
         if self.lang.js_stemmer_rawcode:
             return [
-                path.join(package_dir, 'search', 'non-minified-js', fname)
-                for fname in ('base-stemmer.js', self.lang.js_stemmer_rawcode)
+                _StrPath(_NON_MINIFIED_JS_PATH / 'base-stemmer.js'),
+                _StrPath(_NON_MINIFIED_JS_PATH / self.lang.js_stemmer_rawcode),
             ]
         else:
             return []
@@ -562,15 +585,10 @@ class IndexBuilder:
     def get_js_stemmer_code(self) -> str:
         """Returns JS code that will be inserted into language_data.js."""
         if self.lang.js_stemmer_rawcode:
-            js_dir = path.join(package_dir, 'search', 'minified-js')
-            with open(
-                path.join(js_dir, 'base-stemmer.js'), encoding='utf-8'
-            ) as js_file:
-                base_js = js_file.read()
-            with open(
-                path.join(js_dir, self.lang.js_stemmer_rawcode), encoding='utf-8'
-            ) as js_file:
-                language_js = js_file.read()
+            base_js_path = _NON_MINIFIED_JS_PATH / 'base-stemmer.js'
+            language_js_path = _NON_MINIFIED_JS_PATH / self.lang.js_stemmer_rawcode
+            base_js = base_js_path.read_text(encoding='utf-8')
+            language_js = language_js_path.read_text(encoding='utf-8')
             return (
                 f'{base_js}\n{language_js}\nStemmer = {self.lang.language_name}Stemmer;'
             )
@@ -587,6 +605,9 @@ def _feed_visit_nodes(
 ) -> None:
     if isinstance(node, nodes.comment):
         return
+    elif isinstance(node, nodes.Element) and 'no-search' in node['classes']:
+        # skip nodes marked with a 'no-search' class
+        return
     elif isinstance(node, nodes.raw):
         if 'html' in node.get('format', '').split():
             # Some people might put content in raw HTML that should be searched,

sphinx/search/en.py

@@ -6,19 +6,17 @@ import snowballstemmer
 
 from sphinx.search import SearchLanguage
 
-english_stopwords = set(
-    """
-a  and  are  as  at
-be  but  by
-for
-if  in  into  is  it
-near  no  not
-of  on  or
-such
-that  the  their  then  there  these  they  this  to
-was  will  with
-""".split()
-)
+english_stopwords = {
+    'a', 'and', 'are', 'as', 'at',
+    'be', 'but', 'by',
+    'for',
+    'if', 'in', 'into', 'is', 'it',
+    'near', 'no', 'not',
+    'of', 'on', 'or',
+    'such',
+    'that', 'the', 'their', 'then', 'there', 'these', 'they', 'this', 'to',
+    'was', 'will', 'with',
+}  # fmt: skip
 
 js_porter_stemmer = """
 /**

sphinx/search/fi.py

@@ -95,7 +95,7 @@ kun    | when
 niin   | so
 nyt    | now
 itse   | self
-""")
+""")  # NoQA: E501
 
 
 class SearchFinnish(SearchLanguage):

sphinx/search/ja.py

@@ -13,7 +13,11 @@ from __future__ import annotations
 import os
 import re
 import sys
-from typing import Any
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
 
 try:
     import MeCab  # type: ignore[import-not-found]
@@ -39,8 +43,7 @@ class BaseSplitter:
         self.options = options
 
     def split(self, input: str) -> list[str]:
-        """
-        :param str input:
+        """:param str input:
         :return:
         :rtype: list[str]
         """
@@ -89,7 +92,7 @@ class MecabSplitter(BaseSplitter):
             libpath = ctypes.util.find_library(lib)
         else:
             libpath = None
-            if os.path.exists(lib):
+            if Path(lib).exists():
                 libpath = lib
         if libpath is None:
             msg = 'MeCab dynamic library is not available'
@@ -513,8 +516,7 @@ class DefaultSplitter(BaseSplitter):
 
 
 class SearchJapanese(SearchLanguage):
-    """
-    Japanese search implementation: uses no stemmer, but word splitting is quite
+    """Japanese search implementation: uses no stemmer, but word splitting is quite
     complicated.
     """
 

sphinx/search/nl.py

@@ -109,7 +109,7 @@ uw             |  your
 iemand         |  somebody
 geweest        |  been; past participle of 'be'
 andere         |  other
-""")
+""")  # NoQA: E501
 
 
 class SearchDutch(SearchLanguage):

sphinx/search/zh.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-import os
 import re
+from pathlib import Path
 
 import snowballstemmer
 
@@ -13,22 +13,22 @@ try:
     import jieba  # type: ignore[import-not-found]
 
     JIEBA = True
+    JIEBA_DEFAULT_DICT = Path(jieba.__file__).parent / jieba.DEFAULT_DICT_NAME
 except ImportError:
     JIEBA = False
-
-english_stopwords = set(
-    """
-a  and  are  as  at
-be  but  by
-for
-if  in  into  is  it
-near  no  not
-of  on  or
-such
-that  the  their  then  there  these  they  this  to
-was  will  with
-""".split()
-)
+    JIEBA_DEFAULT_DICT = Path()
+
+english_stopwords = {
+    'a', 'and', 'are', 'as', 'at',
+    'be', 'but', 'by',
+    'for',
+    'if', 'in', 'into', 'is', 'it',
+    'near', 'no', 'not',
+    'of', 'on', 'or',
+    'such',
+    'that', 'the', 'their', 'then', 'there', 'these', 'they', 'this', 'to',
+    'was', 'will', 'with',
+}  # fmt: skip
 
 js_porter_stemmer = """
 /**
@@ -218,9 +218,7 @@ iti|ous|ive|ize)$/;
 
 
 class SearchChinese(SearchLanguage):
-    """
-    Chinese search implementation
-    """
+    """Chinese search implementation"""
 
     lang = 'zh'
     language_name = 'Chinese'
@@ -234,8 +232,8 @@ class SearchChinese(SearchLanguage):
 
     def init(self, options: dict[str, str]) -> None:
         if JIEBA:
-            dict_path = options.get('dict')
-            if dict_path and os.path.isfile(dict_path):
+            dict_path = options.get('dict', JIEBA_DEFAULT_DICT)
+            if dict_path and Path(dict_path).is_file():
                 jieba.load_userdict(dict_path)
 
         self.stemmer = snowballstemmer.stemmer('english')
@@ -260,7 +258,7 @@ class SearchChinese(SearchLanguage):
         stemmed = self.stemmer.stemWord(word.lower())
         should_not_be_stemmed = (
             len(word) >= 3 > len(stemmed) and word in self.latin_terms
-        )  # fmt: skip
+        )
         if should_not_be_stemmed:
             return word.lower()
         return stemmed

sphinx/testing/fixtures.py

@@ -73,11 +73,10 @@ def app_params(
     request: Any,
     test_params: dict[str, Any],
     shared_result: SharedResult,
-    sphinx_test_tempdir: str,
-    rootdir: Path,
+    sphinx_test_tempdir: Path,
+    rootdir: Path | None,
 ) -> _app_params:
-    """
-    Parameters that are specified by 'pytest.mark.sphinx' for
+    """Parameters that are specified by 'pytest.mark.sphinx' for
     sphinx.application.Sphinx initialization
     """
     # ##### process pytest.mark.sphinx
@@ -103,24 +102,31 @@ def app_params(
 
     # ##### prepare Application params
 
-    testroot = kwargs.pop('testroot', 'root')
-    kwargs['srcdir'] = srcdir = sphinx_test_tempdir / kwargs.get('srcdir', testroot)
+    test_root = kwargs.pop('testroot', 'root')
+    kwargs['srcdir'] = srcdir = sphinx_test_tempdir / kwargs.get('srcdir', test_root)
+    copy_test_root = not {'srcdir', 'copy_test_root'}.isdisjoint(kwargs)
 
     # special support for sphinx/tests
-    if rootdir and not srcdir.exists():
-        testroot_path = rootdir / ('test-' + testroot)
-        shutil.copytree(testroot_path, srcdir)
+    if rootdir is not None:
+        test_root_path = rootdir / f'test-{test_root}'
+        if copy_test_root:
+            if test_root_path.is_dir():
+                shutil.copytree(test_root_path, srcdir, dirs_exist_ok=True)
+        else:
+            kwargs['srcdir'] = test_root_path
+
+    # always write to the temporary directory
+    kwargs.setdefault('builddir', srcdir / '_build')
 
     return _app_params(args, kwargs)
 
 
-_app_params = namedtuple('_app_params', 'args,kwargs')
+_app_params = namedtuple('_app_params', 'args,kwargs')  # NoQA: PYI024
 
 
 @pytest.fixture
 def test_params(request: Any) -> dict[str, Any]:
-    """
-    Test parameters that are specified by 'pytest.mark.test_params'
+    """Test parameters that are specified by 'pytest.mark.test_params'
 
     :param Union[str] shared_result:
        If the value is provided, app._status and app._warning objects will be
@@ -148,9 +154,7 @@ def app(
     make_app: Callable[[], SphinxTestApp],
     shared_result: SharedResult,
 ) -> Iterator[SphinxTestApp]:
-    """
-    Provides the 'sphinx.application.Sphinx' object
-    """
+    """Provides the 'sphinx.application.Sphinx' object"""
     args, kwargs = app_params
     app_ = make_app(*args, **kwargs)
     yield app_
@@ -168,24 +172,19 @@ def app(
 
 @pytest.fixture
 def status(app: SphinxTestApp) -> StringIO:
-    """
-    Back-compatibility for testing with previous @with_app decorator
-    """
+    """Back-compatibility for testing with previous @with_app decorator"""
     return app.status
 
 
 @pytest.fixture
 def warning(app: SphinxTestApp) -> StringIO:
-    """
-    Back-compatibility for testing with previous @with_app decorator
-    """
+    """Back-compatibility for testing with previous @with_app decorator"""
     return app.warning
 
 
 @pytest.fixture
 def make_app(test_params: dict[str, Any]) -> Iterator[Callable[[], SphinxTestApp]]:
-    """
-    Provides make_app function to initialize SphinxTestApp instance.
+    """Provides make_app function to initialize SphinxTestApp instance.
     if you want to initialize 'app' in your test function. please use this
     instead of using SphinxTestApp class directory.
     """
@@ -222,9 +221,8 @@ def _shared_result_cache() -> None:
 
 
 @pytest.fixture
-def if_graphviz_found(app: SphinxTestApp) -> None:  # NoQA: PT004
-    """
-    The test will be skipped when using 'if_graphviz_found' fixture and graphviz
+def if_graphviz_found(app: SphinxTestApp) -> None:
+    """The test will be skipped when using 'if_graphviz_found' fixture and graphviz
     dot command is not found.
     """
     graphviz_dot = getattr(app.config, 'graphviz_dot', '')
@@ -246,9 +244,8 @@ def sphinx_test_tempdir(tmp_path_factory: pytest.TempPathFactory) -> Path:
 
 
 @pytest.fixture
-def rollback_sysmodules() -> Iterator[None]:  # NoQA: PT004
-    """
-    Rollback sys.modules to its value before testing to unload modules
+def rollback_sysmodules() -> Iterator[None]:
+    """Rollback sys.modules to its value before testing to unload modules
     during tests.
 
     For example, used in test_ext_autosummary.py to permit unloading the