[mypy] add stubs for color functions (sphinx-doc#12217)

.ruff.toml

@@ -557,7 +557,6 @@ exclude = [
  "sphinx/util/requests.py",
  "sphinx/util/docstrings.py",
  "sphinx/util/rst.py",
- "sphinx/util/console.py",
  "sphinx/util/i18n.py",
  "sphinx/util/fileutil.py",
  "sphinx/util/png.py",

sphinx/application.py

@@ -33,7 +33,7 @@
 from sphinx.util import docutils, logging
 from sphinx.util._pathlib import _StrPath
 from sphinx.util.build_phase import BuildPhase
-from sphinx.util.console import bold # type: ignore[attr-defined]
+from sphinx.util.console import bold
 from sphinx.util.display import progress_message
 from sphinx.util.i18n import CatalogRepository
 from sphinx.util.logging import prefixed_warnings

sphinx/builders/__init__.py

@@ -17,7 +17,7 @@
 from sphinx.locale import __
 from sphinx.util import UnicodeDecodeErrorHandler, get_filetype, import_object, logging, rst
 from sphinx.util.build_phase import BuildPhase
-from sphinx.util.console import bold # type: ignore[attr-defined]
+from sphinx.util.console import bold
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import sphinx_domains
 from sphinx.util.i18n import CatalogInfo, CatalogRepository, docname_to_domain

sphinx/builders/changes.py

@@ -12,7 +12,7 @@
 from sphinx.locale import _, __
 from sphinx.theming import HTMLThemeFactory
 from sphinx.util import logging
-from sphinx.util.console import bold # type: ignore[attr-defined]
+from sphinx.util.console import bold
 from sphinx.util.fileutil import copy_asset_file
 from sphinx.util.osutil import ensuredir, os_path
 

sphinx/builders/gettext.py

@@ -16,7 +16,7 @@
 from sphinx.errors import ThemeError
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import bold # type: ignore[attr-defined]
+from sphinx.util.console import bold
 from sphinx.util.display import status_iterator
 from sphinx.util.i18n import CatalogInfo, docname_to_domain
 from sphinx.util.index_entries import split_index_msg

sphinx/builders/latex/__init__.py

@@ -20,7 +20,7 @@
 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[attr-defined]
+from sphinx.util.console import bold, darkgreen
 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

sphinx/builders/linkcheck.py

@@ -24,13 +24,7 @@
 from sphinx.locale import __
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import encode_uri, logging, requests
-from sphinx.util.console import ( # type: ignore[attr-defined]
- darkgray,
- darkgreen,
- purple,
- red,
- turquoise,
-)
+from sphinx.util.console import darkgray, darkgreen, purple, red, turquoise
 from sphinx.util.http_date import rfc1123_to_epoch
 from sphinx.util.nodes import get_node_line
 

sphinx/builders/manpage.py

@@ -13,7 +13,7 @@
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen # type: ignore[attr-defined]
+from sphinx.util.console import darkgreen
 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

sphinx/builders/singlehtml.py

@@ -11,7 +11,7 @@
 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[attr-defined]
+from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message
 from sphinx.util.nodes import inline_all_toctrees
 

sphinx/builders/texinfo.py

@@ -17,7 +17,7 @@
 from sphinx.errors import NoUri
 from sphinx.locale import _, __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen # type: ignore[attr-defined]
+from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import new_document
 from sphinx.util.fileutil import copy_asset_file

sphinx/cmd/build.py

@@ -22,12 +22,7 @@
 from sphinx.errors import SphinxError, SphinxParallelError
 from sphinx.locale import __
 from sphinx.util._io import TeeStripANSI
-from sphinx.util.console import ( # type: ignore[attr-defined]
- color_terminal,
- nocolor,
- red,
- terminal_safe,
-)
+from sphinx.util.console import 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 ensuredir

sphinx/cmd/make_mode.py

@@ -17,12 +17,7 @@
 
 import sphinx
 from sphinx.cmd.build import build_main
-from sphinx.util.console import ( # type: ignore[attr-defined]
- blue,
- bold,
- color_terminal,
- nocolor,
-)
+from sphinx.util.console import blue, bold, color_terminal, nocolor
 from sphinx.util.osutil import rmtree
 
 if sys.version_info >= (3, 11):

sphinx/cmd/quickstart.py

@@ -31,13 +31,7 @@
 import sphinx.locale
 from sphinx import __display_version__, package_dir
 from sphinx.locale import __
-from sphinx.util.console import ( # type: ignore[attr-defined]
- bold,
- color_terminal,
- colorize,
- nocolor,
- red,
-)
+from sphinx.util.console import bold, color_terminal, colorize, nocolor, red
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxRenderer
 

sphinx/ext/coverage.py

@@ -19,7 +19,7 @@
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import red # type: ignore[attr-defined]
+from sphinx.util.console import red
 from sphinx.util.inspect import safe_getattr
 
 if TYPE_CHECKING:

sphinx/ext/doctest.py

@@ -22,7 +22,7 @@
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import bold # type: ignore[attr-defined]
+from sphinx.util.console import bold
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.osutil import relpath
 

sphinx/util/console.py

@@ -11,6 +11,33 @@
 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
@@ -20,13 +47,15 @@
 
 _CSI = re.escape('\x1b[') # 'ESC [': Control Sequence Introducer
 _ansi_re: re.Pattern[str] = re.compile(
- _CSI + r"""
+ _CSI
+ + r"""
  (
  (\d\d;){0,2}\d\dm # ANSI colour code
  |
  \dK # ANSI Erase in Line
  )""",
- re.VERBOSE | re.ASCII)
+ re.VERBOSE | re.ASCII,
+)
 _ansi_color_re: Final[re.Pattern[str]] = re.compile('\x1b.*?m')
 
 codes: dict[str, str] = {}
@@ -109,28 +138,29 @@ def _strip_escape_sequences(s: str) -> str:
 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',
+ 'reset': '39;49;00m',
+ 'bold': '01m',
+ 'faint': '02m',
+ 'standout': '03m',
  'underline': '04m',
- 'blink':  '05m',
+ 'blink': '05m',
 }
 
 for _name, _value in _attrs.items():
  codes[_name] = '\x1b[' + _value
 
 _colors = [
- ('black',  'darkgray'),
- ('darkred',  'red'),
+ ('black', 'darkgray'),
+ ('darkred', 'red'),
  ('darkgreen', 'green'),
- ('brown',  'yellow'),
- ('darkblue',  'blue'),
- ('purple',  'fuchsia'),
+ ('brown', 'yellow'),
+ ('darkblue', 'blue'),
+ ('purple', 'fuchsia'),
  ('turquoise', 'teal'),
  ('lightgray', 'white'),
 ]

sphinx/util/display.py

@@ -5,7 +5,7 @@
 
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import bold, color_terminal # type: ignore[attr-defined]
+from sphinx.util.console import bold, color_terminal
 
 if False:
  from collections.abc import Iterable, Iterator