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

sphinx/writers/text.py

@@ -1,4 +1,5 @@
 """Custom docutils writer for plain text."""
+
 from __future__ import annotations
 
 import math
@@ -7,7 +8,7 @@ import re
 import textwrap
 from collections.abc import Iterable, Iterator, Sequence
 from itertools import chain, groupby, pairwise
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes, writers
 from docutils.utils import column_width
@@ -27,7 +28,7 @@ class Cell:
     It can span multiple columns or multiple lines.
     """
 
-    def __init__(self, text: str = "", rowspan: int = 1, colspan: int = 1) -> None:
+    def __init__(self, text: str = '', rowspan: int = 1, colspan: int = 1) -> None:
         self.text = text
         self.wrapped: list[str] = []
         self.rowspan = rowspan
@@ -36,7 +37,9 @@ class Cell:
         self.row: int | None = None
 
     def __repr__(self) -> str:
-        return f"<Cell {self.text!r} {self.row}v{self.rowspan}/{self.col}>{self.colspan}>"
+        return (
+            f'<Cell {self.text!r} {self.row}v{self.rowspan}/{self.col}>{self.colspan}>'
+        )
 
     def __hash__(self) -> int:
         return hash((self.col, self.row))
@@ -98,7 +101,7 @@ class Table:
     def __init__(self, colwidth: list[int] | None = None) -> None:
         self.lines: list[list[Cell]] = []
         self.separator = 0
-        self.colwidth: list[int] = (colwidth if colwidth is not None else [])
+        self.colwidth: list[int] = colwidth if colwidth is not None else []
         self.current_line = 0
         self.current_col = 0
 
@@ -150,7 +153,7 @@ class Table:
                 line.append(Cell())
 
     def __repr__(self) -> str:
-        return "\n".join(map(repr, self.lines))
+        return '\n'.join(map(repr, self.lines))
 
     def cell_width(self, cell: Cell, source: list[int]) -> int:
         """Give the cell width, according to the given source (either
@@ -203,55 +206,58 @@ class Table:
         out = []
         self.rewrap()
 
-        def writesep(char: str = "-", lineno: int | None = None) -> str:
+        def writesep(char: str = '-', lineno: int | None = None) -> str:
             """Called on the line *before* lineno.
             Called with no *lineno* for the last sep.
             """
             out: list[str] = []
             for colno, width in enumerate(self.measured_widths):
                 if (
-                    lineno is not None and
-                    lineno > 0 and
-                    self[lineno, colno] is self[lineno - 1, colno]
+                    lineno is not None
+                    and lineno > 0
+                    and self[lineno, colno] is self[lineno - 1, colno]
                 ):
-                    out.append(" " * (width + 2))
+                    out.append(' ' * (width + 2))
                 else:
                     out.append(char * (width + 2))
-            head = "+" if out[0][0] == "-" else "|"
-            tail = "+" if out[-1][0] == "-" else "|"
+            head = '+' if out[0][0] == '-' else '|'
+            tail = '+' if out[-1][0] == '-' else '|'
             glue = [
-                "+" if left[0] == "-" or right[0] == "-" else "|"
+                '+' if left[0] == '-' or right[0] == '-' else '|'
                 for left, right in pairwise(out)
             ]
             glue.append(tail)
-            return head + "".join(chain.from_iterable(zip(out, glue, strict=False)))
+            return head + ''.join(chain.from_iterable(zip(out, glue, strict=False)))
 
         for lineno, line in enumerate(self.lines):
             if self.separator and lineno == self.separator:
-                out.append(writesep("=", lineno))
+                out.append(writesep('=', lineno))
             else:
-                out.append(writesep("-", lineno))
+                out.append(writesep('-', lineno))
             for physical_line in range(self.physical_lines_for_line(line)):
-                linestr = ["|"]
+                linestr = ['|']
                 for colno, cell in enumerate(line):
                     if cell.col != colno:
                         continue
                     if lineno != cell.row:  # NoQA: SIM114
-                        physical_text = ""
+                        physical_text = ''
                     elif physical_line >= len(cell.wrapped):
-                        physical_text = ""
+                        physical_text = ''
                     else:
                         physical_text = cell.wrapped[physical_line]
                     adjust_len = len(physical_text) - column_width(physical_text)
                     linestr.append(
-                        " " +
-                        physical_text.ljust(
-                            self.cell_width(cell, self.measured_widths) + 1 + adjust_len,
-                        ) + "|",
+                        ' '
+                        + physical_text.ljust(
+                            self.cell_width(cell, self.measured_widths)
+                            + 1
+                            + adjust_len,
+                        )
+                        + '|',
                     )
-                out.append("".join(linestr))
-        out.append(writesep("-"))
-        return "\n".join(out)
+                out.append(''.join(linestr))
+        out.append(writesep('-'))
+        return '\n'.join(out)
 
 
 class TextWrapper(textwrap.TextWrapper):
@@ -261,7 +267,8 @@ class TextWrapper(textwrap.TextWrapper):
         r'(\s+|'                                  # any whitespace
         r'(?<=\s)(?::[a-z-]+:)?`\S+|'             # interpreted text start
         r'[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|'   # hyphenated words
-        r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))')   # em-dash
+        r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))'    # em-dash
+    )  # fmt: skip
 
     def _wrap_chunks(self, chunks: list[str]) -> list[str]:
         """The original _wrap_chunks uses len() to calculate width.
@@ -270,7 +277,7 @@ class TextWrapper(textwrap.TextWrapper):
         """
         lines: list[str] = []
         if self.width <= 0:
-            raise ValueError("invalid width %r (must be > 0)" % self.width)
+            raise ValueError('invalid width %r (must be > 0)' % self.width)
 
         chunks.reverse()
 
@@ -315,7 +322,7 @@ class TextWrapper(textwrap.TextWrapper):
         for i, c in enumerate(word):
             total += column_width(c)
             if total > space_left:
-                return word[:i - 1], word[i - 1:]
+                return word[: i - 1], word[i - 1 :]
         return word, ''
 
     def _split(self, text: str) -> list[str]:
@@ -323,8 +330,10 @@ class TextWrapper(textwrap.TextWrapper):
 
         This '_split' splits wide-characters into chunks by one character.
         """
+
         def split(t: str) -> list[str]:
             return super(TextWrapper, self)._split(t)
+
         chunks: list[str] = []
         for chunk in split(text):
             for w, g in groupby(chunk, column_width):
@@ -334,8 +343,9 @@ class TextWrapper(textwrap.TextWrapper):
                     chunks.extend(list(g))
         return chunks
 
-    def _handle_long_word(self, reversed_chunks: list[str], cur_line: list[str],
-                          cur_len: int, width: int) -> None:
+    def _handle_long_word(
+        self, reversed_chunks: list[str], cur_line: list[str], cur_len: int, width: int
+    ) -> None:
         """Override original method for using self._break_word() instead of slice."""
         space_left = max(width - cur_len, 1)
         if self.break_long_words:
@@ -356,10 +366,10 @@ def my_wrap(text: str, width: int = MAXWIDTH, **kwargs: Any) -> list[str]:
     return w.wrap(text)
 
 
-class TextWriter(writers.Writer):  # type: ignore[misc]
+class TextWriter(writers.Writer):  # type: ignore[type-arg]
     supported = ('text',)
     settings_spec = ('No options here.', '', ())
-    settings_defaults: dict[str, Any] = {}
+    settings_defaults: ClassVar[dict[str, Any]] = {}
 
     output: str
 
@@ -368,6 +378,7 @@ class TextWriter(writers.Writer):  # type: ignore[misc]
         self.builder = builder
 
     def translate(self) -> None:
+        assert isinstance(self.document, nodes.document)
         visitor = self.builder.create_translator(self.document, self.builder)
         self.document.walkabout(visitor)
         self.output = cast(TextTranslator, visitor).body
@@ -411,7 +422,10 @@ class TextTranslator(SphinxTranslator):
         self.stateindent.append(indent)
 
     def end_state(
-        self, wrap: bool = True, end: Sequence[str] | None = ('',), first: str | None = None,
+        self,
+        wrap: bool = True,
+        end: Sequence[str] | None = ('',),
+        first: str | None = None,
     ) -> None:
         content = self.states.pop()
         maxindent = sum(self.stateindent)
@@ -429,6 +443,7 @@ class TextTranslator(SphinxTranslator):
             if end:
                 res += end
             result.append((indent, res))
+
         for itemindent, item in content:
             if itemindent == -1:
                 toformat.append(item)  # type: ignore[arg-type]
@@ -453,9 +468,11 @@ class TextTranslator(SphinxTranslator):
 
     def depart_document(self, node: Element) -> None:
         self.end_state()
-        self.body = self.nl.join(line and (' ' * indent + line)
-                                 for indent, lines in self.states[0]
-                                 for line in lines)
+        self.body = self.nl.join(
+            line and (' ' * indent + line)
+            for indent, lines in self.states[0]
+            for line in lines
+        )
         # XXX header/footer?
 
     def visit_section(self, node: Element) -> None:
@@ -623,7 +640,9 @@ class TextTranslator(SphinxTranslator):
         self.param_group_index = 0
         # Counts as what we call a parameter group are either a required parameter, or a
         # set of contiguous optional ones.
-        self.list_is_required_param = [isinstance(c, parameter_group) for c in node.children]
+        self.list_is_required_param = [
+            isinstance(c, parameter_group) for c in node.children
+        ]
         self.required_params_left = sum(self.list_is_required_param)
         self.param_separator = ', '
         self.multi_line_parameter_list = node.get('multi_line_parameter_list', False)
@@ -649,7 +668,9 @@ class TextTranslator(SphinxTranslator):
 
     def visit_desc_parameter(self, node: Element) -> None:
         on_separate_line = self.multi_line_parameter_list
-        if on_separate_line and not (self.is_first_param and self.optional_param_level > 0):
+        if on_separate_line and not (
+            self.is_first_param and self.optional_param_level > 0
+        ):
             self.new_state()
         if self.is_first_param:
             self.is_first_param = False
@@ -664,13 +685,18 @@ class TextTranslator(SphinxTranslator):
 
         is_required = self.list_is_required_param[self.param_group_index]
         if on_separate_line:
-            is_last_group = self.param_group_index + 1 == len(self.list_is_required_param)
+            len_lirp = len(self.list_is_required_param)
+            is_last_group = self.param_group_index + 1 == len_lirp
             next_is_required = (
                 not is_last_group
                 and self.list_is_required_param[self.param_group_index + 1]
             )
             opt_param_left_at_level = self.params_left_at_level > 0
-            if opt_param_left_at_level or is_required and (is_last_group or next_is_required):
+            if (
+                opt_param_left_at_level
+                or is_required
+                and (is_last_group or next_is_required)
+            ):
                 self.add_text(self.param_separator)
                 self.end_state(wrap=False, end=None)
 
@@ -685,8 +711,9 @@ class TextTranslator(SphinxTranslator):
         self.visit_desc_parameter(node)
 
     def visit_desc_optional(self, node: Element) -> None:
-        self.params_left_at_level = sum(isinstance(c, addnodes.desc_parameter)
-                                        for c in node.children)
+        self.params_left_at_level = sum(
+            isinstance(c, addnodes.desc_parameter) for c in node.children
+        )
         self.optional_param_level += 1
         self.max_optional_param_level = self.optional_param_level
         if self.multi_line_parameter_list:
@@ -841,7 +868,7 @@ class TextTranslator(SphinxTranslator):
         raise nodes.SkipNode
 
     def visit_colspec(self, node: Element) -> None:
-        self.table.colwidth.append(node["colwidth"])
+        self.table.colwidth.append(node['colwidth'])
         raise nodes.SkipNode
 
     def visit_tgroup(self, node: Element) -> None:
@@ -871,7 +898,8 @@ class TextTranslator(SphinxTranslator):
 
     def visit_entry(self, node: Element) -> None:
         self.entry = Cell(
-            rowspan=node.get("morerows", 0) + 1, colspan=node.get("morecols", 0) + 1,
+            rowspan=node.get('morerows', 0) + 1,
+            colspan=node.get('morecols', 0) + 1,
         )
         self.new_state(0)
 
@@ -1035,9 +1063,11 @@ class TextTranslator(SphinxTranslator):
     def _depart_admonition(self, node: Element) -> None:
         label = admonitionlabels[node.tagname]
         indent = sum(self.stateindent) + len(label)
-        if (len(self.states[-1]) == 1 and
-                self.states[-1][0][0] == 0 and
-                MAXWIDTH - indent >= sum(len(s) for s in self.states[-1][0][1])):
+        if (
+            len(self.states[-1]) == 1
+            and self.states[-1][0][0] == 0
+            and MAXWIDTH - indent >= sum(len(s) for s in self.states[-1][0][1])
+        ):
             # short text: append text after admonition label
             self.stateindent[-1] += len(label)
             self.end_state(first=label + ': ')
@@ -1114,13 +1144,17 @@ class TextTranslator(SphinxTranslator):
         pass
 
     def visit_paragraph(self, node: Element) -> None:
-        if not isinstance(node.parent, nodes.Admonition) or \
-           isinstance(node.parent, addnodes.seealso):
+        if (
+            not isinstance(node.parent, nodes.Admonition)
+            or isinstance(node.parent, addnodes.seealso)
+        ):  # fmt: skip
             self.new_state(0)
 
     def depart_paragraph(self, node: Element) -> None:
-        if not isinstance(node.parent, nodes.Admonition) or \
-           isinstance(node.parent, addnodes.seealso):
+        if (
+            not isinstance(node.parent, nodes.Admonition)
+            or isinstance(node.parent, addnodes.seealso)
+        ):  # fmt: skip
             self.end_state()
 
     def visit_target(self, node: Element) -> None:
@@ -1143,7 +1177,7 @@ class TextTranslator(SphinxTranslator):
 
     def visit_reference(self, node: Element) -> None:
         if self.add_secnumbers:
-            numbers = node.get("secnumber")
+            numbers = node.get('secnumber')
             if numbers is not None:
                 self.add_text('.'.join(map(str, numbers)) + self.secnumber_suffix)
 

sphinx/writers/xml.py

@@ -18,19 +18,20 @@ class XMLWriter(BaseXMLWriter):  # type: ignore[misc]
         self.builder = builder
 
         # A lambda function to generate translator lazily
-        self.translator_class = lambda document: self.builder.create_translator(document)
+        self.translator_class = lambda document: self.builder.create_translator(
+            document
+        )
 
     def translate(self, *args: Any, **kwargs: Any) -> None:
-        self.document.settings.newlines = \
-            self.document.settings.indents = \
+        self.document.settings.newlines = self.document.settings.indents = (
             self.builder.env.config.xml_pretty
+        )
         self.document.settings.xml_declaration = True
         self.document.settings.doctype_declaration = True
         return super().translate()
 
 
 class PseudoXMLWriter(BaseXMLWriter):  # type: ignore[misc]
-
     supported = ('pprint', 'pformat', 'pseudoxml')
     """Formats this writer supports."""
 

sphinx-8.1.0.dist-info/LICENSE.rst

@@ -0,0 +1,31 @@
+License for Sphinx
+==================
+
+Unless otherwise indicated, all code in the Sphinx project is licenced under the
+two clause BSD licence below.
+
+Copyright (c) 2007-2024 by the Sphinx team (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

{sphinx-8.0.2.dist-info → sphinx-8.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: Sphinx
-Version: 8.0.2
+Version: 8.1.0
 Summary: Python documentation generator
 Author-email: Georg Brandl <georg@python.org>
 Requires-Python: >=3.10
@@ -41,12 +41,12 @@ Classifier: Topic :: Text Processing :: Markup
 Classifier: Topic :: Text Processing :: Markup :: HTML
 Classifier: Topic :: Text Processing :: Markup :: LaTeX
 Classifier: Topic :: Utilities
-Requires-Dist: sphinxcontrib-applehelp
-Requires-Dist: sphinxcontrib-devhelp
-Requires-Dist: sphinxcontrib-jsmath
-Requires-Dist: sphinxcontrib-htmlhelp>=2.0.0
+Requires-Dist: sphinxcontrib-applehelp>=1.0.7
+Requires-Dist: sphinxcontrib-devhelp>=1.0.6
+Requires-Dist: sphinxcontrib-htmlhelp>=2.0.6
+Requires-Dist: sphinxcontrib-jsmath>=1.0.1
+Requires-Dist: sphinxcontrib-qthelp>=1.0.6
 Requires-Dist: sphinxcontrib-serializinghtml>=1.1.9
-Requires-Dist: sphinxcontrib-qthelp
 Requires-Dist: Jinja2>=3.1
 Requires-Dist: Pygments>=2.17
 Requires-Dist: docutils>=0.20,<0.22
@@ -60,16 +60,18 @@ Requires-Dist: tomli>=2; python_version < '3.11'
 Requires-Dist: colorama>=0.4.6; sys_platform == 'win32'
 Requires-Dist: sphinxcontrib-websupport ; extra == "docs"
 Requires-Dist: flake8>=6.0 ; extra == "lint"
-Requires-Dist: ruff==0.5.5 ; extra == "lint"
-Requires-Dist: mypy==1.11.0 ; extra == "lint"
+Requires-Dist: ruff==0.6.9 ; extra == "lint"
+Requires-Dist: mypy==1.11.1 ; extra == "lint"
 Requires-Dist: sphinx-lint>=0.9 ; extra == "lint"
 Requires-Dist: types-colorama==0.4.15.20240311 ; extra == "lint"
 Requires-Dist: types-defusedxml==0.7.0.20240218 ; extra == "lint"
-Requires-Dist: types-docutils==0.21.0.20240724 ; extra == "lint"
-Requires-Dist: types-Pillow==10.2.0.20240520 ; extra == "lint"
+Requires-Dist: types-docutils==0.21.0.20241005 ; extra == "lint"
+Requires-Dist: types-Pillow==10.2.0.20240822 ; extra == "lint"
 Requires-Dist: types-Pygments==2.18.0.20240506 ; extra == "lint"
-Requires-Dist: types-requests>=2.30.0 ; extra == "lint"
+Requires-Dist: types-requests==2.32.0.20240914 ; extra == "lint"
+Requires-Dist: types-urllib3==1.26.25.14 ; extra == "lint"
 Requires-Dist: tomli>=2 ; extra == "lint"
+Requires-Dist: pyright==1.1.384 ; extra == "lint"
 Requires-Dist: pytest>=6.0 ; extra == "lint"
 Requires-Dist: pytest>=8.0 ; extra == "test"
 Requires-Dist: defusedxml>=0.7.1 ; extra == "test"