Respect NO_COLOR for automatic debug and pprint highlighting (#170)

Co-authored-by: Samuel Colvin <s@muelcolvin.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: 3 people

devtools/ansi.py

@@ -4,7 +4,7 @@
 from enum import IntEnum
 from typing import Any, TextIO
 
-from .utils import isatty
+from .utils import auto_highlight
 
 __all__ = 'sformat', 'sprint'
 
@@ -151,7 +151,7 @@ def __call__(
         file: TextIO | None = None,
         **print_kwargs: Any,
     ) -> None:
-        text = sformat(input, *styles, reset=reset, apply=isatty(file))
+        text = sformat(input, *styles, reset=reset, apply=auto_highlight(file))
         print(text, flush=flush, file=file, **print_kwargs)
 
     def __getattr__(self, item: str) -> str:

devtools/prettier.py

@@ -6,7 +6,7 @@
 from functools import cache
 from typing import TYPE_CHECKING, Any, TextIO, cast
 
-from .utils import DataClassType, LaxMapping, SQLAlchemyClassType, env_true, isatty
+from .utils import DataClassType, LaxMapping, SQLAlchemyClassType, auto_highlight, env_true
 
 if TYPE_CHECKING:
     from pygments.formatters import Terminal256Formatter
@@ -316,5 +316,5 @@ def _format_fields(
 
 
 def pprint(s: Any, file: TextIO | None = None) -> None:
-    highlight = isatty(file) if force_highlight is None else force_highlight
+    highlight = auto_highlight(file) if force_highlight is None else force_highlight
     print(pformat(s, highlight=highlight), file=file, flush=True)

devtools/utils.py

@@ -6,6 +6,7 @@
     'DataClassType',
     'LaxMapping',
     'SQLAlchemyClassType',
+    'auto_highlight',
     'env_bool',
     'env_true',
     'is_literal',
@@ -99,8 +100,16 @@ def use_highlight(highlight: bool | None = None, file_: Any = None) -> bool:
         return highlight
 
     if sys.platform == 'win32':  # pragma: no cover
-        return isatty(file_) and activate_win_color()
-    return isatty(file_)
+        return auto_highlight(file_) and activate_win_color()
+    return auto_highlight(file_)
+
+
+def auto_highlight(file_: Any = None) -> bool:
+    """
+    Whether to colour output when nothing has asked for it explicitly: only when writing to a terminal and
+    `NO_COLOR` (https://no-color.org/) is unset or empty.
+    """
+    return not os.getenv('NO_COLOR') and isatty(file_)
 
 
 def is_literal(s: Any) -> bool:

docs/usage.md

@@ -18,6 +18,13 @@ and readable way to print stuff during development. (If you know why this is, I'
 * each argument is printed "pretty" on a new line, see [prettier print](#prettier-print)
 * if `pygments` is installed the output is highlighted
 
+`debug`, `pprint` and `sprint` highlight output automatically when writing to a terminal. Set
+[`NO_COLOR`](https://no-color.org/) to any non-empty value (including `0`) to disable this default
+highlighting. An empty value keeps automatic highlighting enabled. The program-specific
+`PY_DEVTOOLS_HIGHLIGHT` setting overrides `NO_COLOR`, and an explicit `Debug(highlight=True)` or
+`Debug(highlight=False)` takes precedence over both environment variables. Explicit highlighting
+with `pformat(value, highlight=True)` also remains available.
+
 A more complex example of `debug` shows more of what it can do.
 
 ```py

tests/test_colors.py

@@ -0,0 +1,91 @@
+import io
+
+import pytest
+
+import devtools.prettier
+from devtools import Debug, pformat, pprint, sprint
+
+
+@pytest.mark.parametrize('printer', ['debug', 'pprint'])
+@pytest.mark.parametrize('tty', [False, True])
+@pytest.mark.parametrize('no_color', [None, '', '1', '0', 'false'])
+def test_no_color_default(monkeypatch: pytest.MonkeyPatch, printer: str, tty: bool, no_color: str | None):
+    monkeypatch.delenv('PY_DEVTOOLS_HIGHLIGHT', raising=False)
+    monkeypatch.setattr(devtools.prettier, 'force_highlight', None)
+    if no_color is None:
+        monkeypatch.delenv('NO_COLOR', raising=False)
+    else:
+        monkeypatch.setenv('NO_COLOR', no_color)
+    output = io.StringIO()
+    monkeypatch.setattr(output, 'isatty', lambda: tty)
+    monkeypatch.setattr('devtools.utils.activate_win_color', lambda: True)
+
+    if printer == 'debug':
+        Debug()(1, file_=output)
+    else:
+        pprint(1, file=output)
+
+    assert ('\x1b[' in output.getvalue()) is (tty and not no_color)
+
+
+@pytest.mark.parametrize('printer', ['debug', 'pprint'])
+@pytest.mark.parametrize('tty', [False, True])
+@pytest.mark.parametrize('highlight', [False, True])
+def test_no_color_config_override(monkeypatch: pytest.MonkeyPatch, printer: str, tty: bool, highlight: bool):
+    monkeypatch.setenv('NO_COLOR', '1')
+    monkeypatch.setenv('PY_DEVTOOLS_HIGHLIGHT', str(highlight))
+    monkeypatch.setattr(devtools.prettier, 'force_highlight', highlight)
+    output = io.StringIO()
+    monkeypatch.setattr(output, 'isatty', lambda: tty)
+
+    if printer == 'debug':
+        Debug()(1, file_=output)
+    else:
+        pprint(1, file=output)
+
+    assert ('\x1b[' in output.getvalue()) is highlight
+
+
+@pytest.mark.parametrize('highlight', [False, True])
+@pytest.mark.parametrize('tty', [False, True])
+def test_no_color_explicit_debug_override(monkeypatch: pytest.MonkeyPatch, highlight: bool, tty: bool):
+    monkeypatch.setenv('NO_COLOR', '1')
+    monkeypatch.setenv('PY_DEVTOOLS_HIGHLIGHT', str(not highlight))
+    output = io.StringIO()
+    monkeypatch.setattr(output, 'isatty', lambda: tty)
+
+    Debug(highlight=highlight)(1, file_=output)
+
+    assert ('\x1b[' in output.getvalue()) is highlight
+
+
+def test_no_color_explicit_pformat_override(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv('NO_COLOR', '1')
+    assert '\x1b[' not in pformat(1)
+    assert '\x1b[' in pformat(1, highlight=True)
+
+
+def test_pprint_highlight_config_snapshot(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv('NO_COLOR', raising=False)
+    monkeypatch.setenv('PY_DEVTOOLS_HIGHLIGHT', 'True')
+    monkeypatch.setattr(devtools.prettier, 'force_highlight', None)
+    output = io.StringIO()
+    monkeypatch.setattr(output, 'isatty', lambda: False)
+
+    pprint(1, file=output)
+
+    assert output.getvalue() == '1\n'
+
+
+@pytest.mark.parametrize('no_color', [None, '', '1'])
+def test_sprint_no_color(monkeypatch: pytest.MonkeyPatch, no_color: str | None):
+    if no_color is None:
+        monkeypatch.delenv('NO_COLOR', raising=False)
+    else:
+        monkeypatch.setenv('NO_COLOR', no_color)
+    output = io.StringIO()
+    monkeypatch.setattr(output, 'isatty', lambda: True)
+
+    sprint('hello', sprint.green, file=output)
+
+    assert ('\x1b[' in output.getvalue()) is (not no_color)

tests/test_utils.py

@@ -37,14 +37,16 @@ def test_use_highlight_manually_set(monkeypatch: pytest.MonkeyPatch):
 
 @pytest.mark.skipif(sys.platform == 'win32', reason='windows os')
 def test_use_highlight_auto_not_win(monkeypatch: pytest.MonkeyPatch):
-    monkeypatch.delenv('TEST_DONT_USE_HIGHLIGHT', raising=False)
+    monkeypatch.delenv('NO_COLOR', raising=False)
+    monkeypatch.delenv('PY_DEVTOOLS_HIGHLIGHT', raising=False)
     monkeypatch.setattr(devtools.utils, 'isatty', fake_isatty)
     assert use_highlight() is True
 
 
 @pytest.mark.skipif(sys.platform != 'win32', reason='not windows os')
 def test_use_highlight_auto_win(monkeypatch: pytest.MonkeyPatch):
-    monkeypatch.delenv('TEST_DONT_USE_HIGHLIGHT', raising=False)
+    monkeypatch.delenv('NO_COLOR', raising=False)
+    monkeypatch.delenv('PY_DEVTOOLS_HIGHLIGHT', raising=False)
     monkeypatch.setattr(devtools.utils, 'isatty', fake_isatty)
 
     assert use_highlight() is True