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

sphinx/writers/latex.py

@@ -8,19 +8,19 @@ from __future__ import annotations
 
 import re
 from collections import defaultdict
+from collections.abc import Iterable
 from os import path
-from typing import TYPE_CHECKING, Any, Iterable, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes, writers
-from docutils.nodes import Element, Node, Text
 
 from sphinx import addnodes, highlighting
-from sphinx.domains import IndexEntry
 from sphinx.domains.std import StandardDomain
 from sphinx.errors import SphinxError
 from sphinx.locale import _, __, admonitionlabels
-from sphinx.util import logging, split_into, texescape
+from sphinx.util import logging, texescape
 from sphinx.util.docutils import SphinxTranslator
+from sphinx.util.index_entries import split_index_msg
 from sphinx.util.nodes import clean_astext, get_prev_node
 from sphinx.util.template import LaTeXRenderer
 from sphinx.util.texescape import tex_replace_map
@@ -29,11 +29,14 @@ try:
     from docutils.utils.roman import toRoman
 except ImportError:
     # In Debian/Ubuntu, roman package is provided as roman, not as docutils.utils.roman
-    from roman import toRoman  # type: ignore
+    from roman import toRoman  # type: ignore[no-redef]
 
 if TYPE_CHECKING:
+    from docutils.nodes import Element, Node, Text
+
     from sphinx.builders.latex import LaTeXBuilder
     from sphinx.builders.latex.theming import Theme
+    from sphinx.domains import IndexEntry
 
 
 logger = logging.getLogger(__name__)
@@ -74,12 +77,11 @@ class LaTeXWriter(writers.Writer):
     ))
     settings_defaults: dict[str, Any] = {}
 
-    output = None
+    theme: Theme
 
     def __init__(self, builder: LaTeXBuilder) -> None:
         super().__init__()
         self.builder = builder
-        self.theme: Theme = None
 
     def translate(self) -> None:
         visitor = self.builder.create_translator(self.document, self.builder, self.theme)
@@ -109,17 +111,18 @@ class Table:
         elif 'colorrows' in self.classes:
             self.styles.append('colorrows')
         self.colcount = 0
-        self.colspec: str = None
-        self.colsep: str = None
+        self.colspec: str = ''
         if 'booktabs' in self.styles or 'borderless' in self.styles:
-            self.colsep = ''
+            self.colsep: str | None = ''
         elif 'standard' in self.styles:
             self.colsep = '|'
+        else:
+            self.colsep = None
         self.colwidths: list[int] = []
         self.has_problematic = False
         self.has_oldproblematic = False
         self.has_verbatim = False
-        self.caption: list[str] = None
+        self.caption: list[str] = []
         self.stubs: list[int] = []
 
         # current position
@@ -168,6 +171,7 @@ class Table:
             return self.colspec
 
         _colsep = self.colsep
+        assert _colsep is not None
         if self.colwidths and 'colwidths-given' in self.classes:
             total = sum(self.colwidths)
             colspecs = [r'\X{%d}{%d}' % (width, total) for width in self.colwidths]
@@ -659,6 +663,7 @@ class LaTeXTranslator(SphinxTranslator):
     def depart_title(self, node: Element) -> None:
         self.in_title = 0
         if isinstance(node.parent, nodes.table):
+            assert self.table is not None
             self.table.caption = self.popbody()
         else:
             self.body.append(self.context.pop())
@@ -991,6 +996,7 @@ class LaTeXTranslator(SphinxTranslator):
 
     def visit_table(self, node: Element) -> None:
         if len(self.tables) == 1:
+            assert self.table is not None
             if self.table.get_table_type() == 'longtable':
                 raise UnsupportedError(
                     '%s:%s: longtable does not support nesting a table.' %
@@ -1003,26 +1009,28 @@ class LaTeXTranslator(SphinxTranslator):
                 '%s:%s: deeply nested tables are not implemented.' %
                 (self.curfilestack[-1], node.line or ''))
 
-        self.tables.append(Table(node))
-        if self.table.colsep is None:
-            self.table.colsep = '' if (
-                'booktabs' in self.builder.config.latex_table_style or
-                'borderless' in self.builder.config.latex_table_style
-            ) else '|'
+        table = Table(node)
+        self.tables.append(table)
+        if table.colsep is None:
+            table.colsep = '|' * (
+                'booktabs' not in self.builder.config.latex_table_style
+                and 'borderless' not in self.builder.config.latex_table_style
+            )
         if self.next_table_colspec:
-            self.table.colspec = '{%s}' % self.next_table_colspec + CR
-            if '|' in self.table.colspec:
-                self.table.styles.append('vlines')
-                self.table.colsep = '|'
+            table.colspec = '{%s}' % self.next_table_colspec + CR
+            if '|' in table.colspec:
+                table.styles.append('vlines')
+                table.colsep = '|'
             else:
-                self.table.styles.append('novlines')
-                self.table.colsep = ''
+                table.styles.append('novlines')
+                table.colsep = ''
             if 'colwidths-given' in node.get('classes', []):
                 logger.info(__('both tabularcolumns and :widths: option are given. '
                                ':widths: is ignored.'), location=node)
         self.next_table_colspec = None
 
     def depart_table(self, node: Element) -> None:
+        assert self.table is not None
         labels = self.hypertarget_to(node)
         table_type = self.table.get_table_type()
         table = self.render(table_type + '.tex_t',
@@ -1034,6 +1042,7 @@ class LaTeXTranslator(SphinxTranslator):
         self.tables.pop()
 
     def visit_colspec(self, node: Element) -> None:
+        assert self.table is not None
         self.table.colcount += 1
         if 'colwidth' in node:
             self.table.colwidths.append(node['colwidth'])
@@ -1050,6 +1059,7 @@ class LaTeXTranslator(SphinxTranslator):
         pass
 
     def visit_thead(self, node: Element) -> None:
+        assert self.table is not None
         # Redirect head output until header is finished.
         self.pushbody(self.table.header)
 
@@ -1059,6 +1069,7 @@ class LaTeXTranslator(SphinxTranslator):
         self.popbody()
 
     def visit_tbody(self, node: Element) -> None:
+        assert self.table is not None
         # Redirect body output until table is finished.
         self.pushbody(self.table.body)
 
@@ -1068,6 +1079,7 @@ class LaTeXTranslator(SphinxTranslator):
         self.popbody()
 
     def visit_row(self, node: Element) -> None:
+        assert self.table is not None
         self.table.col = 0
         _colsep = self.table.colsep
         # fill columns if the row starts with the bottom of multirow cell
@@ -1087,9 +1099,11 @@ class LaTeXTranslator(SphinxTranslator):
                                  (cell.width, _colsep, _colsep, cell.cell_id))
 
     def depart_row(self, node: Element) -> None:
+        assert self.table is not None
         self.body.append(r'\\' + CR)
         cells = [self.table.cell(self.table.row, i) for i in range(self.table.colcount)]
-        underlined = [cell.row + cell.height == self.table.row + 1 for cell in cells]
+        underlined = [cell.row + cell.height == self.table.row + 1  # type: ignore[union-attr]
+                      for cell in cells]
         if all(underlined):
             self.body.append(r'\sphinxhline')
         else:
@@ -1098,7 +1112,7 @@ class LaTeXTranslator(SphinxTranslator):
             if underlined[0] is False:
                 i = 1
                 while i < self.table.colcount and underlined[i] is False:
-                    if cells[i - 1].cell_id != cells[i].cell_id:
+                    if cells[i - 1].cell_id != cells[i].cell_id:  # type: ignore[union-attr]
                         self.body.append(r'\sphinxvlinecrossing{%d}' % i)
                     i += 1
             while i < self.table.colcount:
@@ -1108,17 +1122,19 @@ class LaTeXTranslator(SphinxTranslator):
                 i += j
                 i += 1
                 while i < self.table.colcount and underlined[i] is False:
-                    if cells[i - 1].cell_id != cells[i].cell_id:
+                    if cells[i - 1].cell_id != cells[i].cell_id:  # type: ignore[union-attr]
                         self.body.append(r'\sphinxvlinecrossing{%d}' % i)
                     i += 1
             self.body.append(r'\sphinxfixclines{%d}' % self.table.colcount)
         self.table.row += 1
 
     def visit_entry(self, node: Element) -> None:
+        assert self.table is not None
         if self.table.col > 0:
             self.body.append('&')
         self.table.add_cell(node.get('morerows', 0) + 1, node.get('morecols', 0) + 1)
         cell = self.table.cell()
+        assert cell is not None
         context = ''
         _colsep = self.table.colsep
         if cell.width > 1:
@@ -1165,7 +1181,9 @@ class LaTeXTranslator(SphinxTranslator):
 
         self.body.append(self.context.pop())
 
+        assert self.table is not None
         cell = self.table.cell()
+        assert cell is not None
         self.table.col += cell.width
         _colsep = self.table.colsep
 
@@ -1482,8 +1500,9 @@ class LaTeXTranslator(SphinxTranslator):
                 length = self.latex_image_length(node['width'])
             elif isinstance(node[0], nodes.image) and 'width' in node[0]:
                 length = self.latex_image_length(node[0]['width'])
-            self.body.append(BLANKLINE)     # Insert a blank line to prevent infinite loop
-                                            # https://github.com/sphinx-doc/sphinx/issues/7059
+            # Insert a blank line to prevent an infinite loop
+            # https://github.com/sphinx-doc/sphinx/issues/7059
+            self.body.append(BLANKLINE)
             self.body.append(r'\begin{wrapfigure}{%s}{%s}' %
                              ('r' if node['align'] == 'right' else 'l', length or '0pt') + CR)
             self.body.append(r'\centering')
@@ -1626,8 +1645,8 @@ class LaTeXTranslator(SphinxTranslator):
             if has_dup_label(prev):
                 ids = node['ids'][:]  # copy to avoid side-effects
                 while has_dup_label(prev):
-                    ids.remove(prev['refid'])  # type: ignore
-                    prev = get_prev_node(prev)
+                    ids.remove(prev['refid'])  # type: ignore[index]
+                    prev = get_prev_node(prev)  # type: ignore[arg-type]
             else:
                 ids = iter(node['ids'])  # read-only iterator
         else:
@@ -1672,37 +1691,32 @@ class LaTeXTranslator(SphinxTranslator):
             if ismain:
                 m = '|spxpagem'
             try:
+                parts = tuple(map(escape, split_index_msg(type, string)))
+                styled = tuple(map(style, parts))
                 if type == 'single':
                     try:
-                        p1, p2 = (escape(x) for x in split_into(2, 'single', string))
-                        P1, P2 = style(p1), style(p2)
+                        p1, p2 = parts
+                        P1, P2 = styled
                         self.body.append(fr'\index{{{p1}@{P1}!{p2}@{P2}{m}}}')
                     except ValueError:
-                        p = escape(split_into(1, 'single', string)[0])
-                        P = style(p)
+                        p, = parts
+                        P, = styled
                         self.body.append(fr'\index{{{p}@{P}{m}}}')
                 elif type == 'pair':
-                    p1, p2 = (escape(x) for x in split_into(2, 'pair', string))
-                    P1, P2 = style(p1), style(p2)
-                    self.body.append(r'\index{%s@%s!%s@%s%s}\index{%s@%s!%s@%s%s}' %
-                                     (p1, P1, p2, P2, m, p2, P2, p1, P1, m))
+                    p1, p2 = parts
+                    P1, P2 = styled
+                    self.body.append(fr'\index{{{p1}@{P1}!{p2}@{P2}{m}}}'
+                                     fr'\index{{{p2}@{P2}!{p1}@{P1}{m}}}')
                 elif type == 'triple':
-                    p1, p2, p3 = (escape(x) for x in split_into(3, 'triple', string))
-                    P1, P2, P3 = style(p1), style(p2), style(p3)
+                    p1, p2, p3 = parts
+                    P1, P2, P3 = styled
                     self.body.append(
-                        r'\index{%s@%s!%s %s@%s %s%s}'
-                        r'\index{%s@%s!%s, %s@%s, %s%s}'
-                        r'\index{%s@%s!%s %s@%s %s%s}' %
-                        (p1, P1, p2, p3, P2, P3, m,
-                         p2, P2, p3, p1, P3, P1, m,
-                         p3, P3, p1, p2, P1, P2, m))
-                elif type == 'see':
-                    p1, p2 = (escape(x) for x in split_into(2, 'see', string))
-                    P1 = style(p1)
-                    self.body.append(fr'\index{{{p1}@{P1}|see{{{p2}}}}}')
-                elif type == 'seealso':
-                    p1, p2 = (escape(x) for x in split_into(2, 'seealso', string))
-                    P1 = style(p1)
+                        fr'\index{{{p1}@{P1}!{p2} {p3}@{P2} {P3}{m}}}'
+                        fr'\index{{{p2}@{P2}!{p3}, {p1}@{P3}, {P1}{m}}}'
+                        fr'\index{{{p3}@{P3}!{p1} {p2}@{P1} {P2}{m}}}')
+                elif type in {'see', 'seealso'}:
+                    p1, p2 = parts
+                    P1, _P2 = styled
                     self.body.append(fr'\index{{{p1}@{P1}|see{{{p2}}}}}')
                 else:
                     logger.warning(__('unknown index entry type %s found'), type)

sphinx/writers/manpage.py

@@ -2,21 +2,25 @@
 
 from __future__ import annotations
 
-from typing import Any, Iterable, cast
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Element
 from docutils.writers.manpage import Translator as BaseTranslator
 from docutils.writers.manpage import Writer
 
 from sphinx import addnodes
-from sphinx.builders import Builder
 from sphinx.locale import _, admonitionlabels
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxTranslator
 from sphinx.util.i18n import format_date
 from sphinx.util.nodes import NodeMatcher
 
+if TYPE_CHECKING:
+    from docutils.nodes import Element
+
+    from sphinx.builders import Builder
+
 logger = logging.getLogger(__name__)
 
 
@@ -240,7 +244,7 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):
             super().visit_term(node)
 
     # overwritten -- we don't want source comments to show up
-    def visit_comment(self, node: Element) -> None:  # type: ignore
+    def visit_comment(self, node: Element) -> None:  # type: ignore[override]
         raise nodes.SkipNode
 
     # overwritten -- added ensure_eol()
@@ -308,7 +312,7 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):
         self.body.append(self.defs['reference'][0])
         # avoid repeating escaping code... fine since
         # visit_Text calls astext() and only works on that afterwards
-        self.visit_Text(node)  # type: ignore
+        self.visit_Text(node)  # type: ignore[arg-type]
         self.body.append(self.defs['reference'][1])
 
         uri = node.get('refuri', '')

sphinx/writers/texinfo.py

@@ -4,14 +4,13 @@ from __future__ import annotations
 
 import re
 import textwrap
+from collections.abc import Iterable, Iterator
 from os import path
-from typing import TYPE_CHECKING, Any, Iterable, Iterator, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes, writers
-from docutils.nodes import Element, Node, Text
 
 from sphinx import __display_version__, addnodes
-from sphinx.domains import IndexEntry
 from sphinx.domains.index import IndexDomain
 from sphinx.errors import ExtensionError
 from sphinx.locale import _, __, admonitionlabels
@@ -21,7 +20,10 @@ from sphinx.util.i18n import format_date
 from sphinx.writers.latex import collected_footnote
 
 if TYPE_CHECKING:
+    from docutils.nodes import Element, Node, Text
+
     from sphinx.builders.texinfo import TexinfoBuilder
+    from sphinx.domains import IndexEntry
 
 
 logger = logging.getLogger(__name__)
@@ -232,9 +234,9 @@ class TexinfoTranslator(SphinxTranslator):
         # filename
         if not elements['filename']:
             elements['filename'] = self.document.get('source') or 'untitled'
-            if elements['filename'][-4:] in ('.txt', '.rst'):  # type: ignore
-                elements['filename'] = elements['filename'][:-4]  # type: ignore
-            elements['filename'] += '.info'  # type: ignore
+            if elements['filename'][-4:] in ('.txt', '.rst'):  # type: ignore[index]
+                elements['filename'] = elements['filename'][:-4]  # type: ignore[index]
+            elements['filename'] += '.info'  # type: ignore[operator]
         # direntry
         if self.settings.texinfo_dir_entry:
             entry = self.format_menu_entry(
@@ -428,7 +430,7 @@ class TexinfoTranslator(SphinxTranslator):
             entries = self.node_menus[name]
             if not entries:
                 return
-            self.body.append('\n%s\n\n' % (self.escape(self.node_names[name],)))
+            self.body.append(f'\n{self.escape(self.node_names[name], )}\n\n')
             self.add_menu_entries(entries)
             for subentry in entries:
                 _add_detailed_menu(subentry)
@@ -862,7 +864,7 @@ class TexinfoTranslator(SphinxTranslator):
         except (KeyError, IndexError) as exc:
             raise nodes.SkipNode from exc
         # footnotes are repeated for each reference
-        footnode.walkabout(self)  # type: ignore
+        footnode.walkabout(self)  # type: ignore[union-attr]
         raise nodes.SkipChildren
 
     def visit_citation(self, node: Element) -> None:
@@ -1213,7 +1215,7 @@ class TexinfoTranslator(SphinxTranslator):
         width = self.tex_image_length(node.get('width', ''))
         height = self.tex_image_length(node.get('height', ''))
         alt = self.escape_arg(node.get('alt', ''))
-        filename = f"{self.elements['filename'][:-5]}-figures/{name}"  # type: ignore
+        filename = f"{self.elements['filename'][:-5]}-figures/{name}"  # type: ignore[index]
         self.body.append('\n@image{%s,%s,%s,%s,%s}\n' %
                          (filename, width, height, alt, ext[1:]))
 

sphinx/writers/text.py

@@ -5,11 +5,11 @@ import math
 import os
 import re
 import textwrap
+from collections.abc import Generator, Iterable, Sequence
 from itertools import chain, groupby
-from typing import TYPE_CHECKING, Any, Generator, Iterable, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes, writers
-from docutils.nodes import Element, Text
 from docutils.utils import column_width
 
 from sphinx import addnodes
@@ -17,6 +17,8 @@ from sphinx.locale import _, admonitionlabels
 from sphinx.util.docutils import SphinxTranslator
 
 if TYPE_CHECKING:
+    from docutils.nodes import Element, Text
+
     from sphinx.builders.text import TextBuilder
 
 
@@ -154,7 +156,8 @@ class Table:
         This takes into account cells spanning multiple columns.
         """
         if cell.row is None or cell.col is None:
-            raise ValueError('Cell co-ordinates have not been set')
+            msg = 'Cell co-ordinates have not been set'
+            raise ValueError(msg)
         width = 0
         for i in range(self[cell.row, cell.col].colspan):
             width += source[cell.col + i]
@@ -179,7 +182,8 @@ class Table:
             if not cell.wrapped:
                 continue
             if cell.row is None or cell.col is None:
-                raise ValueError('Cell co-ordinates have not been set')
+                msg = 'Cell co-ordinates have not been set'
+                raise ValueError(msg)
             width = math.ceil(max(column_width(x) for x in cell.wrapped) / cell.colspan)
             for col in range(cell.col, cell.col + cell.colspan):
                 self.measured_widths[col] = max(self.measured_widths[col], width)
@@ -415,7 +419,7 @@ class TextTranslator(SphinxTranslator):
         self.stateindent.append(indent)
 
     def end_state(
-        self, wrap: bool = True, end: list[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)
@@ -435,10 +439,10 @@ class TextTranslator(SphinxTranslator):
             result.append((indent, res))
         for itemindent, item in content:
             if itemindent == -1:
-                toformat.append(item)  # type: ignore
+                toformat.append(item)  # type: ignore[arg-type]
             else:
                 do_format()
-                result.append((indent + itemindent, item))  # type: ignore
+                result.append((indent + itemindent, item))  # type: ignore[arg-type]
                 toformat = []
         do_format()
         if first is not None and result:
@@ -520,7 +524,7 @@ class TextTranslator(SphinxTranslator):
         else:
             char = '^'
         text = ''
-        text = ''.join(x[1] for x in self.states.pop() if x[0] == -1)  # type: ignore
+        text = ''.join(x[1] for x in self.states.pop() if x[0] == -1)  # type: ignore[misc]
         if self.add_secnumbers:
             text = self.get_section_number_string(node) + text
         self.stateindent.pop()
@@ -890,7 +894,8 @@ class TextTranslator(SphinxTranslator):
 
     def visit_table(self, node: Element) -> None:
         if hasattr(self, 'table'):
-            raise NotImplementedError('Nested tables are not supported.')
+            msg = 'Nested tables are not supported.'
+            raise NotImplementedError(msg)
         self.new_state(0)
         self.table = Table()
 

sphinx/writers/xml.py

@@ -2,11 +2,12 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from docutils.writers.docutils_xml import Writer as BaseXMLWriter
 
-from sphinx.builders import Builder
+if TYPE_CHECKING:
+    from sphinx.builders import Builder
 
 
 class XMLWriter(BaseXMLWriter):

{sphinx-7.1.2.dist-info → sphinx-7.2.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
 Name: Sphinx
-Version: 7.1.2
+Version: 7.2.0
 Summary: Python documentation generator
 Author-email: Georg Brandl <georg@python.org>
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
@@ -18,10 +18,11 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Framework :: Sphinx
@@ -47,7 +48,7 @@ Requires-Dist: sphinxcontrib-htmlhelp>=2.0.0
 Requires-Dist: sphinxcontrib-serializinghtml>=1.1.5
 Requires-Dist: sphinxcontrib-qthelp
 Requires-Dist: Jinja2>=3.0
-Requires-Dist: Pygments>=2.13
+Requires-Dist: Pygments>=2.14
 Requires-Dist: docutils>=0.18.1,<0.21
 Requires-Dist: snowballstemmer>=2.0
 Requires-Dist: babel>=2.9
@@ -68,7 +69,8 @@ Requires-Dist: docutils-stubs ; extra == "lint"
 Requires-Dist: types-requests ; extra == "lint"
 Requires-Dist: pytest>=4.6 ; extra == "test"
 Requires-Dist: html5lib ; extra == "test"
-Requires-Dist: cython ; extra == "test"
+Requires-Dist: cython>=3.0 ; extra == "test"
+Requires-Dist: setuptools>=67.0 ; extra == "test"
 Requires-Dist: filelock ; extra == "test"
 Project-URL: Changelog, https://www.sphinx-doc.org/en/master/changes.html
 Project-URL: Code, https://github.com/sphinx-doc/sphinx