🐛 fix: strip ANSI colors from usage under PYTHON_COLORS=1 (#356)

On Python 3.14 argparse colors its usage output, and
`_colorize.can_colorize` consults `PYTHON_COLORS` before `NO_COLOR`. A
doc build under `PYTHON_COLORS=1` therefore ignored the `NO_COLOR=1` the
directive sets, and every usage block came out as `usage:
^[[0m^[[1;35mprog^[[0m ...`; the `usage: ` prefix sat inside escape
codes as well, so the 7-character slice removed the wrong text. 🎨

The environment patch around `format_usage` now sets `PYTHON_COLORS=0`
alongside `NO_COLOR=1`, which is the combination the interpreter treats
as plain output regardless of the caller's shell.

Author: gaborbernat

CHANGELOG.md

@@ -12,6 +12,7 @@ All notable changes to this project will be documented in this file.
 - Leave apostrophes inside words (`don't`, `it's`) alone in help text instead of turning them into broken inline
   literals.
 - Make `:hook:` intercept `parse_intermixed_args()` as well as `parse_args()`.
+- Keep ANSI color codes out of usage blocks when `PYTHON_COLORS=1` is set on Python 3.14 or newer.
 
 ## 1.13.1
 

roots/test-python-colors/conf.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+os.environ["PYTHON_COLORS"] = "1"
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True

roots/test-python-colors/index.rst

@@ -0,0 +1,3 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make

roots/test-python-colors/parser.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(prog="prog", add_help=False)
+    parser.add_argument("--flag", help="a flag")
+    parser.add_subparsers().add_parser("run", add_help=False).add_argument("--magic", help="magic")
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -399,7 +399,8 @@ def _mk_usage(self, parser: ArgumentParser) -> literal_block:
 
     @contextmanager
     def _no_color(self) -> Iterator[None]:
-        with patch.dict(os.environ, {"NO_COLOR": "1"}, clear=False):
+        # PYTHON_COLORS=1 outranks NO_COLOR in argparse, so both must be set to get plain text
+        with patch.dict(os.environ, {"NO_COLOR": "1", "PYTHON_COLORS": "0"}, clear=False):
             yield
 
 

tests/test_logic.py

@@ -273,6 +273,36 @@ def test_option_role_as_html(build_outcome: str, warning: StringIO) -> None:
     assert not warning.getvalue()
 
 
+@pytest.mark.sphinx(buildername="text", testroot="python-colors")
+def test_usage_ignores_python_colors(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog [--flag FLAG] {run} ...
+
+
+prog options
+============
+
+* **"--flag"** "FLAG" - a flag
+
+
+prog run
+========
+
+   prog run [--magic MAGIC]
+
+
+prog run options
+----------------
+
+* **"--magic"** "MAGIC" - magic
+"""
+    )
+
+
 @pytest.mark.sphinx(buildername="text", testroot="ref-duplicate-label")
 def test_ref_duplicate_label(build_outcome: tuple[str, str], warning: StringIO) -> None:
     assert build_outcome