From cb8a28dd7e11a7a0a5bc9694163fc164433e2f36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?=
 <10796600+picnixz@users.noreply.github.com>
Date: Mon, 1 Apr 2024 13:45:47 +0200
Subject: [PATCH] [mypy] add stubs for color functions (#12217)

---
 .ruff.toml                        |  1 -
 sphinx/application.py             |  2 +-
 sphinx/builders/__init__.py       |  2 +-
 sphinx/builders/changes.py        |  2 +-
 sphinx/builders/gettext.py        |  2 +-
 sphinx/builders/latex/__init__.py |  2 +-
 sphinx/builders/linkcheck.py      |  8 +----
 sphinx/builders/manpage.py        |  2 +-
 sphinx/builders/singlehtml.py     |  2 +-
 sphinx/builders/texinfo.py        |  2 +-
 sphinx/cmd/build.py               |  7 +---
 sphinx/cmd/make_mode.py           |  7 +---
 sphinx/cmd/quickstart.py          |  8 +----
 sphinx/ext/coverage.py            |  2 +-
 sphinx/ext/doctest.py             |  2 +-
 sphinx/util/console.py            | 54 ++++++++++++++++++++++++-------
 sphinx/util/display.py            |  2 +-
 17 files changed, 57 insertions(+), 50 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 6c336188e..de42679ba 100644
--- a/.ruff.toml
+++ b/.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",
diff --git a/sphinx/application.py b/sphinx/application.py
index 1de0693ba..7d16d9ab2 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -33,7 +33,7 @@ from sphinx.registry import SphinxComponentRegistry
 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
diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py
index 878f5d6ac..9bcc8c7b1 100644
--- a/sphinx/builders/__init__.py
+++ b/sphinx/builders/__init__.py
@@ -17,7 +17,7 @@ from sphinx.errors import SphinxError
 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
diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py
index 7d5e0044e..b233e85cd 100644
--- a/sphinx/builders/changes.py
+++ b/sphinx/builders/changes.py
@@ -12,7 +12,7 @@ from sphinx.domains.changeset import ChangeSetDomain
 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
 
diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py
index 3928f9f93..35abf1fd7 100644
--- a/sphinx/builders/gettext.py
+++ b/sphinx/builders/gettext.py
@@ -16,7 +16,7 @@ from sphinx.builders import Builder
 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
diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py
index fd140dd06..2b176f925 100644
--- a/sphinx/builders/latex/__init__.py
+++ b/sphinx/builders/latex/__init__.py
@@ -20,7 +20,7 @@ from sphinx.environment.adapters.asset import ImageAdapter
 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
diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py
index 83f45e471..89a3543e8 100644
--- a/sphinx/builders/linkcheck.py
+++ b/sphinx/builders/linkcheck.py
@@ -24,13 +24,7 @@ from sphinx.deprecation import RemovedInSphinx80Warning
 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
 
diff --git a/sphinx/builders/manpage.py b/sphinx/builders/manpage.py
index bf01d017c..93b381d38 100644
--- a/sphinx/builders/manpage.py
+++ b/sphinx/builders/manpage.py
@@ -13,7 +13,7 @@ from sphinx import addnodes
 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
diff --git a/sphinx/builders/singlehtml.py b/sphinx/builders/singlehtml.py
index f9ce8cea2..87590544f 100644
--- a/sphinx/builders/singlehtml.py
+++ b/sphinx/builders/singlehtml.py
@@ -11,7 +11,7 @@ from sphinx.builders.html import StandaloneHTMLBuilder
 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
 
diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py
index 226ce690f..8d5a1aa6d 100644
--- a/sphinx/builders/texinfo.py
+++ b/sphinx/builders/texinfo.py
@@ -17,7 +17,7 @@ from sphinx.environment.adapters.asset import ImageAdapter
 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
diff --git a/sphinx/cmd/build.py b/sphinx/cmd/build.py
index bf3fa3400..be23e0b90 100644
--- a/sphinx/cmd/build.py
+++ b/sphinx/cmd/build.py
@@ -22,12 +22,7 @@ from sphinx.application import Sphinx
 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
diff --git a/sphinx/cmd/make_mode.py b/sphinx/cmd/make_mode.py
index ee237ae15..01929469c 100644
--- a/sphinx/cmd/make_mode.py
+++ b/sphinx/cmd/make_mode.py
@@ -17,12 +17,7 @@ from typing import TYPE_CHECKING
 
 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):
diff --git a/sphinx/cmd/quickstart.py b/sphinx/cmd/quickstart.py
index fe1a29a14..8fb7eebae 100644
--- a/sphinx/cmd/quickstart.py
+++ b/sphinx/cmd/quickstart.py
@@ -31,13 +31,7 @@ from docutils.utils import column_width
 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
 
diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py
index 92afd868c..cfe093623 100644
--- a/sphinx/ext/coverage.py
+++ b/sphinx/ext/coverage.py
@@ -19,7 +19,7 @@ import sphinx
 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:
diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py
index fe133900c..e6ba27439 100644
--- a/sphinx/ext/doctest.py
+++ b/sphinx/ext/doctest.py
@@ -22,7 +22,7 @@ import sphinx
 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
 
diff --git a/sphinx/util/console.py b/sphinx/util/console.py
index 8a5fe3d51..bba1109dc 100644
--- a/sphinx/util/console.py
+++ b/sphinx/util/console.py
@@ -11,6 +11,33 @@ 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
@@ -20,13 +47,15 @@ except ImportError:
 
 _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'),
 ]
diff --git a/sphinx/util/display.py b/sphinx/util/display.py
index 967c80573..3cb8d9729 100644
--- a/sphinx/util/display.py
+++ b/sphinx/util/display.py
@@ -5,7 +5,7 @@ from typing import Any, Callable, TypeVar
 
 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