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

sphinx/util/console.py

@@ -2,71 +2,44 @@
 
 from __future__ import annotations
 
-import os
-import re
 import shutil
-import sys
-from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:
-    from typing import Final
-
-    # fmt: off
-    def reset(text: str) -> str: ...  # NoQA: E704
-    def bold(text: str) -> str: ...  # NoQA: E704
-    def faint(text: str) -> str: ...  # NoQA: E704
-    def standout(text: str) -> str: ...  # NoQA: E704
-    def underline(text: str) -> str: ...  # NoQA: E704
-    def blink(text: str) -> str: ...  # NoQA: E704
-
-    def black(text: str) -> str: ...  # NoQA: E704
-    def white(text: str) -> str: ...  # NoQA: E704
-    def red(text: str) -> str: ...  # NoQA: E704
-    def green(text: str) -> str: ...  # NoQA: E704
-    def yellow(text: str) -> str: ...  # NoQA: E704
-    def blue(text: str) -> str: ...  # NoQA: E704
-    def fuchsia(text: str) -> str: ...  # NoQA: E704
-    def teal(text: str) -> str: ...  # NoQA: E704
-
-    def darkgray(text: str) -> str: ...  # NoQA: E704
-    def lightgray(text: str) -> str: ...  # NoQA: E704
-    def darkred(text: str) -> str: ...  # NoQA: E704
-    def darkgreen(text: str) -> str: ...  # NoQA: E704
-    def brown(text: str) -> str: ...  # NoQA: E704
-    def darkblue(text: str) -> str: ...  # NoQA: E704
-    def purple(text: str) -> str: ...  # NoQA: E704
-    def turquoise(text: str) -> str: ...  # NoQA: E704
-    # fmt: on
-
-try:
-    # check if colorama is installed to support color on Windows
-    import colorama
-
-    COLORAMA_AVAILABLE = True
-except ImportError:
-    COLORAMA_AVAILABLE = False
-
-_CSI: Final[str] = re.escape('\x1b[')  # 'ESC [': Control Sequence Introducer
-
-# Pattern matching ANSI control sequences containing colors.
-_ansi_color_re: Final[re.Pattern[str]] = re.compile(r'\x1b\[(?:\d+;){0,2}\d*m')
-
-_ansi_re: Final[re.Pattern[str]] = re.compile(
-    _CSI
-    + r"""
-    (?:
-      (?:\d+;){0,2}\d*m     # ANSI color code    ('m' is equivalent to '0m')
-    |
-      [012]?K               # ANSI Erase in Line ('K' is equivalent to '0K')
-    )""",
-    re.VERBOSE | re.ASCII,
+import sphinx._cli.util.colour
+from sphinx._cli.util.colour import (  # NoQA: F401
+    _create_input_mode_colour_func,
+    black,
+    blink,
+    blue,
+    bold,
+    brown,
+    colourise,
+    darkblue,
+    darkgray,
+    darkgreen,
+    darkred,
+    disable_colour,
+    enable_colour,
+    faint,
+    fuchsia,
+    green,
+    lightgray,
+    purple,
+    red,
+    reset,
+    standout,
+    teal,
+    terminal_supports_colour,
+    turquoise,
+    underline,
+    white,
+    yellow,
 )
-"""Pattern matching ANSI CSI colors (SGR) and erase line (EL) sequences.
+from sphinx._cli.util.errors import strip_escape_sequences
 
-See :func:`strip_escape_sequences` for details.
-"""
-
-codes: dict[str, str] = {}
+color_terminal = terminal_supports_colour
+nocolor = disable_colour
+coloron = enable_colour
+strip_colors = strip_escape_sequences
 
 
 def terminal_safe(s: str) -> str:
@@ -83,7 +56,7 @@ _tw: int = get_terminal_width()
 
 
 def term_width_line(text: str) -> str:
-    if not codes:
+    if sphinx._cli.util.colour._COLOURING_DISABLED:
         # if no coloring, don't output fancy backspaces
         return text + '\n'
     else:
@@ -91,121 +64,13 @@ def term_width_line(text: str) -> str:
         return text.ljust(_tw + len(text) - len(strip_escape_sequences(text))) + '\r'
 
 
-def color_terminal() -> bool:
-    if 'NO_COLOR' in os.environ:
-        return False
-    if sys.platform == 'win32' and COLORAMA_AVAILABLE:
-        colorama.just_fix_windows_console()
-        return True
-    if 'FORCE_COLOR' in os.environ:
-        return True
-    if not hasattr(sys.stdout, 'isatty'):
-        return False
-    if not sys.stdout.isatty():
-        return False
-    if 'COLORTERM' in os.environ:
-        return True
-    term = os.environ.get('TERM', 'dumb').lower()
-    return term in ('xterm', 'linux') or 'color' in term
-
-
-def nocolor() -> None:
-    if sys.platform == 'win32' and COLORAMA_AVAILABLE:
-        colorama.deinit()
-    codes.clear()
-
-
-def coloron() -> None:
-    codes.update(_orig_codes)
-
-
 def colorize(name: str, text: str, input_mode: bool = False) -> str:
-    def escseq(name: str) -> str:
-        # Wrap escape sequence with ``\1`` and ``\2`` to let readline know
-        # it is non-printable characters
-        # ref: https://tiswww.case.edu/php/chet/readline/readline.html
-        #
-        # Note: This hack does not work well in Windows (see #5059)
-        escape = codes.get(name, '')
-        if input_mode and escape and sys.platform != 'win32':
-            return '\1' + escape + '\2'
-        else:
-            return escape
-
-    return escseq(name) + text + escseq('reset')
-
-
-def strip_colors(s: str) -> str:
-    """Remove the ANSI color codes in a string *s*.
-
-    .. caution::
-
-       This function is not meant to be used in production and should only
-       be used for testing Sphinx's output messages.
-
-    .. seealso:: :func:`strip_escape_sequences`
-    """
-    return _ansi_color_re.sub('', s)
-
-
-def strip_escape_sequences(text: str, /) -> str:
-    r"""Remove the ANSI CSI colors and "erase in line" sequences.
-
-    Other `escape sequences `__ (e.g., VT100-specific functions) are not
-    supported and only control sequences *natively* known to Sphinx (i.e.,
-    colors declared in this module and "erase entire line" (``'\x1b[2K'``))
-    are eliminated by this function.
-
-    .. caution::
-
-       This function is not meant to be used in production and should only
-       be used for testing Sphinx's output messages that were not tempered
-       with by third-party extensions.
-
-    .. versionadded:: 7.3
-
-       This function is added as an *experimental* feature.
-
-    __ https://en.wikipedia.org/wiki/ANSI_escape_code
-    """
-    return _ansi_re.sub('', text)
-
-
-def create_color_func(name: str) -> None:
-    def inner(text: str) -> str:
-        return colorize(name, text)
-
-    globals()[name] = inner
-
-
-_attrs = {
-    'reset': '39;49;00m',
-    'bold': '01m',
-    'faint': '02m',
-    'standout': '03m',
-    'underline': '04m',
-    'blink': '05m',
-}
-
-for __name, __value in _attrs.items():
-    codes[__name] = '\x1b[' + __value
-
-_colors = [
-    ('black', 'darkgray'),
-    ('darkred', 'red'),
-    ('darkgreen', 'green'),
-    ('brown', 'yellow'),
-    ('darkblue', 'blue'),
-    ('purple', 'fuchsia'),
-    ('turquoise', 'teal'),
-    ('lightgray', 'white'),
-]
-
-for __i, (__dark, __light) in enumerate(_colors, 30):
-    codes[__dark] = '\x1b[%im' % __i
-    codes[__light] = '\x1b[%im' % (__i + 60)
-
-_orig_codes = codes.copy()
-
-for _name in codes:
-    create_color_func(_name)
+    if input_mode:
+        colour_func = globals()[name]
+        escape_code = getattr(colour_func, '__escape_code', '')
+        if not escape_code:
+            return colour_func(text)
+        inner = _create_input_mode_colour_func(escape_code)
+        return inner(text)
+
+    return colourise(name, text)

sphinx/util/display.py

@@ -2,16 +2,15 @@ from __future__ import annotations
 
 import functools
 
+from sphinx._cli.util.colour import bold, terminal_supports_colour
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import bold, color_terminal
 
-if False:
+TYPE_CHECKING = False
+if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
     from types import TracebackType
-    from typing import Any, TypeVar
-
-    from typing_extensions import ParamSpec
+    from typing import Any, ParamSpec, TypeVar
 
     T = TypeVar('T')
     P = ParamSpec('P')
@@ -37,12 +36,12 @@ def status_iterator(
     stringify_func: Callable[[Any], str] = display_chunk,
 ) -> Iterator[T]:
     # printing on a single line requires ANSI control sequences
-    single_line = verbosity < 1 and color_terminal()
+    single_line = verbosity < 1 and terminal_supports_colour()
     bold_summary = bold(summary)
     if length == 0:
         logger.info(bold_summary, nonl=True)
         for item in iterable:
-            logger.info(stringify_func(item) + ' ', nonl=True, color=color)
+            logger.info('%s ', stringify_func(item), nonl=True, color=color)
             yield item
     else:
         for i, item in enumerate(iterable, start=1):
@@ -80,14 +79,14 @@ class progress_message:
     ) -> bool:
         prefix = '' if self.nonl else bold(self.message + ': ')
         if isinstance(val, SkipProgressMessage):
-            logger.info(prefix + __('skipped'))
+            logger.info(prefix + __('skipped'))  # NoQA: G003
             if val.args:
                 logger.info(*val.args)
             return True
         elif val:
-            logger.info(prefix + __('failed'))
+            logger.info(prefix + __('failed'))  # NoQA: G003
         else:
-            logger.info(prefix + __('done'))
+            logger.info(prefix + __('done'))  # NoQA: G003
 
         return False
 

sphinx/util/docfields.py

@@ -7,10 +7,9 @@ be domain-specifically transformed to a more appealing presentation.
 from __future__ import annotations
 
 import contextlib
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
-from docutils.nodes import Element, Node
 
 from sphinx import addnodes
 from sphinx.locale import __
@@ -18,12 +17,20 @@ from sphinx.util import logging
 from sphinx.util.nodes import get_node_line
 
 if TYPE_CHECKING:
+    from typing import TypeAlias, TypeVar
+
+    from docutils.nodes import Element, Node
     from docutils.parsers.rst.states import Inliner
 
     from sphinx.directives import ObjectDescription
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import TextlikeNode
 
+    ObjDescT = TypeVar('ObjDescT')
+    _FieldEntry: TypeAlias = tuple[str, list[Node]]
+    _FieldTypes: TypeAlias = dict[str, list[Node]]
+    _EntriesTriple: TypeAlias = tuple['Field', _FieldEntry | list[_FieldEntry], Element]
+
 logger = logging.getLogger(__name__)
 
 
@@ -131,14 +138,14 @@ class Field:
             )
         ]
 
-    def make_entry(self, fieldarg: str, content: list[Node]) -> tuple[str, list[Node]]:
-        return (fieldarg, content)
+    def make_entry(self, fieldarg: str, content: list[Node]) -> _FieldEntry:
+        return fieldarg, content
 
     def make_field(
         self,
-        types: dict[str, list[Node]],
+        types: _FieldTypes,
         domain: str,
-        item: tuple,
+        item: _FieldEntry,
         env: BuildEnvironment | None = None,
         inliner: Inliner | None = None,
         location: Element | None = None,
@@ -181,8 +188,7 @@ class Field:
 
 
 class GroupedField(Field):
-    """
-    A doc field that is grouped; i.e., all fields of that type will be
+    """A doc field that is grouped; i.e., all fields of that type will be
     transformed into one field with its body being a bulleted list.  It always
     has an argument.  The argument can be linked using the given *rolename*.
     GroupedField should be used for doc fields that can occur more than once.
@@ -210,9 +216,9 @@ class GroupedField(Field):
 
     def make_field(
         self,
-        types: dict[str, list[Node]],
+        types: _FieldTypes,
         domain: str,
-        items: tuple,
+        items: list[_FieldEntry],  # type: ignore[override]
         env: BuildEnvironment | None = None,
         inliner: Inliner | None = None,
         location: Element | None = None,
@@ -237,7 +243,7 @@ class GroupedField(Field):
             listnode += nodes.list_item('', par)
 
         if len(items) == 1 and self.can_collapse:
-            list_item = cast(nodes.list_item, listnode[0])
+            list_item = cast('nodes.list_item', listnode[0])
             fieldbody = nodes.field_body('', list_item[0])
             return nodes.field('', fieldname, fieldbody)
 
@@ -246,8 +252,7 @@ class GroupedField(Field):
 
 
 class TypedField(GroupedField):
-    """
-    A doc field that is grouped and has type information for the arguments.  It
+    """A doc field that is grouped and has type information for the arguments.  It
     always has an argument.  The argument can be linked using the given
     *rolename*, the type using the given *typerolename*.
 
@@ -283,9 +288,9 @@ class TypedField(GroupedField):
 
     def make_field(
         self,
-        types: dict[str, list[Node]],
+        types: _FieldTypes,
         domain: str,
-        items: tuple,
+        items: list[_FieldEntry],  # type: ignore[override]
         env: BuildEnvironment | None = None,
         inliner: Inliner | None = None,
         location: Element | None = None,
@@ -338,14 +343,13 @@ class TypedField(GroupedField):
 
 
 class DocFieldTransformer:
-    """
-    Transforms field lists in "doc field" syntax into better-looking
+    """Transforms field lists in "doc field" syntax into better-looking
     equivalents, using the field type definitions given on a domain.
     """
 
     typemap: dict[str, tuple[Field, bool]]
 
-    def __init__(self, directive: ObjectDescription) -> None:
+    def __init__(self, directive: ObjectDescription[ObjDescT]) -> None:
         self.directive = directive
 
         self.typemap = directive.get_field_type_map()
@@ -359,115 +363,129 @@ class DocFieldTransformer:
 
     def transform(self, node: nodes.field_list) -> None:
         """Transform a single field list *node*."""
-        typemap = self.typemap
-
-        entries: list[nodes.field | tuple[Field, Any, Element]] = []
+        entries: list[nodes.field | _EntriesTriple] = []
         groupindices: dict[str, int] = {}
-        types: dict[str, dict] = {}
+        types: dict[str, _FieldTypes] = {}
 
         # step 1: traverse all fields and collect field types and content
-        for field in cast(list[nodes.field], node):
-            assert len(field) == 2
-            field_name = cast(nodes.field_name, field[0])
-            field_body = cast(nodes.field_body, field[1])
+        for field in cast('list[nodes.field]', node):
+            self._transform_step_1(field, entries, types, groupindices)
+
+        new_list = self._transform_step_2(entries, types)
+        node.replace_self(new_list)
+
+    def _transform_step_1(
+        self,
+        field: nodes.field,
+        entries: list[nodes.field | _EntriesTriple],
+        types: dict[str, _FieldTypes],
+        group_indices: dict[str, int],
+    ) -> None:
+        assert len(field) == 2
+        field_name = cast('nodes.field_name', field[0])
+        field_body = cast('nodes.field_body', field[1])
+        try:
+            # split into field type and argument
+            fieldtype_name, fieldarg = field_name.astext().split(None, 1)
+        except ValueError:
+            # maybe an argument-less field type?
+            fieldtype_name, fieldarg = field_name.astext(), ''
+        typedesc, is_typefield = self.typemap.get(fieldtype_name, (None, None))
+
+        # collect the content, trying not to keep unnecessary paragraphs
+        if _is_single_paragraph(field_body):
+            paragraph = cast('nodes.paragraph', field_body[0])
+            content = paragraph.children
+        else:
+            content = field_body.children
+
+        # sort out unknown fields
+        if typedesc is None or typedesc.has_arg != bool(fieldarg):
+            # either the field name is unknown, or the argument doesn't
+            # match the spec; capitalize field name and be done with it
+            new_fieldname = fieldtype_name[0:1].upper() + fieldtype_name[1:]
+            if fieldarg:
+                new_fieldname += ' ' + fieldarg
+            field_name[0] = nodes.Text(new_fieldname)
+            entries.append(field)
+
+            # but if this has a type then we can at least link it
+            if (
+                typedesc
+                and is_typefield
+                and content
+                and len(content) == 1
+                and isinstance(content[0], nodes.Text)
+            ):
+                typed_field = cast('TypedField', typedesc)
+                target = content[0].astext()
+                xrefs = typed_field.make_xrefs(
+                    typed_field.typerolename,
+                    self.directive.domain or '',
+                    target,
+                    contnode=content[0],
+                    env=self.directive.env,
+                )
+                if _is_single_paragraph(field_body):
+                    paragraph = cast('nodes.paragraph', field_body[0])
+                    paragraph.clear()
+                    paragraph.extend(xrefs)
+                else:
+                    field_body.clear()
+                    field_body += nodes.paragraph('', '', *xrefs)
+
+            return
+
+        typename = typedesc.name
+
+        # if the field specifies a type, put it in the types collection
+        if is_typefield:
+            # filter out only inline nodes; others will result in invalid
+            # markup being written out
+            content = [n for n in content if isinstance(n, nodes.Inline | nodes.Text)]
+            if content:
+                types.setdefault(typename, {})[fieldarg] = content
+            return
+
+        # also support syntax like ``:param type name:``
+        if typedesc.is_typed:
             try:
-                # split into field type and argument
-                fieldtype_name, fieldarg = field_name.astext().split(None, 1)
+                argtype, argname = fieldarg.rsplit(None, 1)
             except ValueError:
-                # maybe an argument-less field type?
-                fieldtype_name, fieldarg = field_name.astext(), ''
-            typedesc, is_typefield = typemap.get(fieldtype_name, (None, None))
-
-            # collect the content, trying not to keep unnecessary paragraphs
-            if _is_single_paragraph(field_body):
-                paragraph = cast(nodes.paragraph, field_body[0])
-                content = paragraph.children
+                pass
             else:
-                content = field_body.children
-
-            # sort out unknown fields
-            if typedesc is None or typedesc.has_arg != bool(fieldarg):
-                # either the field name is unknown, or the argument doesn't
-                # match the spec; capitalize field name and be done with it
-                new_fieldname = fieldtype_name[0:1].upper() + fieldtype_name[1:]
-                if fieldarg:
-                    new_fieldname += ' ' + fieldarg
-                field_name[0] = nodes.Text(new_fieldname)
-                entries.append(field)
-
-                # but if this has a type then we can at least link it
-                if (
-                    typedesc
-                    and is_typefield
-                    and content
-                    and len(content) == 1
-                    and isinstance(content[0], nodes.Text)
-                ):
-                    typed_field = cast(TypedField, typedesc)
-                    target = content[0].astext()
-                    xrefs = typed_field.make_xrefs(
-                        typed_field.typerolename,
-                        self.directive.domain or '',
-                        target,
-                        contnode=content[0],
-                        env=self.directive.state.document.settings.env,
-                    )
-                    if _is_single_paragraph(field_body):
-                        paragraph = cast(nodes.paragraph, field_body[0])
-                        paragraph.clear()
-                        paragraph.extend(xrefs)
-                    else:
-                        field_body.clear()
-                        field_body += nodes.paragraph('', '', *xrefs)
-
-                continue
-
-            typename = typedesc.name
-
-            # if the field specifies a type, put it in the types collection
-            if is_typefield:
-                # filter out only inline nodes; others will result in invalid
-                # markup being written out
-                content = [
-                    n for n in content if isinstance(n, nodes.Inline | nodes.Text)
-                ]
-                if content:
-                    types.setdefault(typename, {})[fieldarg] = content
-                continue
-
-            # also support syntax like ``:param type name:``
-            if typedesc.is_typed:
-                try:
-                    argtype, argname = fieldarg.rsplit(None, 1)
-                except ValueError:
-                    pass
-                else:
-                    types.setdefault(typename, {})[argname] = [nodes.Text(argtype)]
-                    fieldarg = argname
-
-            translatable_content = nodes.inline(field_body.rawsource, translatable=True)
-            translatable_content.document = field_body.parent.document
-            translatable_content.source = field_body.parent.source
-            translatable_content.line = field_body.parent.line
-            translatable_content += content
-
-            # grouped entries need to be collected in one entry, while others
-            # get one entry per field
-            if typedesc.is_grouped:
-                if typename in groupindices:
-                    group = cast(
-                        tuple[Field, list, Node], entries[groupindices[typename]]
-                    )
-                else:
-                    groupindices[typename] = len(entries)
-                    group = (typedesc, [], field)
-                    entries.append(group)
-                new_entry = typedesc.make_entry(fieldarg, [translatable_content])
-                group[1].append(new_entry)
+                types.setdefault(typename, {})[argname] = [nodes.Text(argtype)]
+                fieldarg = argname
+
+        translatable_content = nodes.inline(field_body.rawsource, translatable=True)
+        translatable_content.document = field_body.parent.document
+        translatable_content.source = field_body.parent.source
+        translatable_content.line = field_body.parent.line
+        translatable_content += content
+
+        # grouped entries need to be collected in one entry, while others
+        # get one entry per field
+        if typedesc.is_grouped:
+            if typename in group_indices:
+                group = cast(
+                    'tuple[Field, list[_FieldEntry], Node]',
+                    entries[group_indices[typename]],
+                )
             else:
-                new_entry = typedesc.make_entry(fieldarg, [translatable_content])
-                entries.append((typedesc, new_entry, field))
+                group_indices[typename] = len(entries)
+                group = (typedesc, [], field)
+                entries.append(group)
+            new_entry = typedesc.make_entry(fieldarg, [translatable_content])
+            group[1].append(new_entry)
+        else:
+            new_entry = typedesc.make_entry(fieldarg, [translatable_content])
+            entries.append((typedesc, new_entry, field))
 
+    def _transform_step_2(
+        self,
+        entries: list[nodes.field | _EntriesTriple],
+        types: dict[str, _FieldTypes],
+    ) -> nodes.field_list:
         # step 2: all entries are collected, construct the new field list
         new_list = nodes.field_list()
         for entry in entries:
@@ -477,16 +495,16 @@ class DocFieldTransformer:
             else:
                 fieldtype, items, location = entry
                 fieldtypes = types.get(fieldtype.name, {})
-                env = self.directive.state.document.settings.env
+                env = self.directive.env
                 inliner = self.directive.state.inliner
                 domain = self.directive.domain or ''
                 new_list += fieldtype.make_field(
                     fieldtypes,
                     domain,
-                    items,
+                    items,  # type: ignore[arg-type]
                     env=env,
                     inliner=inliner,
                     location=location,
                 )
 
-        node.replace_self(new_list)
+        return new_list

sphinx/util/docstrings.py

@@ -20,7 +20,7 @@ def separate_metadata(s: str | None) -> tuple[str | None, dict[str, str]]:
         return s, metadata
 
     for line in prepare_docstring(s):
-        if line.strip() == '':
+        if not line.strip():
             in_other_element = False
             lines.append(line)
         else: