lib-detect-testenv 3.0.3__tar.gz → 3.0.4__tar.gz

{lib_detect_testenv-3.0.3 → lib_detect_testenv-3.0.4}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.4] 2026-08-01 00:14:59
+### Fixed
+- **Console output no longer crashes on a legacy codepage.** A Windows console at codepage 1252
+  hands Python an `errors="strict"` stream, so writing a non-ASCII character such as a check mark
+  raised `UnicodeEncodeError: 'charmap' codec can't encode character` and the command exited
+  non-zero *after* its work had already succeeded. Click does not protect against this, and Rich
+  raises the same way through its own writer. The new `safe_console` module degrades at the sink:
+  a UTF-8 terminal still receives the character, and only a stream that cannot encode it sees
+  `[OK]` / `[X]` / `[!]`. Every `click.echo` call site routes through it, and a test fails if a
+  module reaches for `click.echo` or builds an unwrapped `Console(file=sys.stdout)` again.
+
+
 ## [3.0.3] 2026-07-24 16:01:54
 
 ### Fixed

{lib_detect_testenv-3.0.3 → lib_detect_testenv-3.0.4}/Makefile

@@ -1,4 +1,4 @@
-# BMK MAKEFILE 3.13.0
+# BMK MAKEFILE 3.14.0
 # do not alter this file - it might be overwritten on new versions of BMK
 # if You want to alter it, remove the first line # BMK MAKEFILE 1.0 - then it is a custom makefile and will not be overwritten
 # bmk Makefile - thin wrapper using `uv tool upgrade` for persistent bmk
@@ -186,7 +186,7 @@ endif
 # BMK_MIN floors the FALLBACK install. The upgrade path does not consult it: uv re-resolves
 # the requirement recorded at install time, which is itself a `bmk>=...`, so it always lands
 # on the newest release and clears the floor anyway.
-BMK_MIN := 3.13.0
+BMK_MIN := 3.14.0
 
 # Absent env, missing check, or damaged env - all three mean "do not upgrade, rebuild".
 # `test -x` keeps a fresh machine quiet: there is no interpreter to run yet.

{lib_detect_testenv-3.0.3 → lib_detect_testenv-3.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_detect_testenv
-Version: 3.0.3
+Version: 3.0.4
 Summary: Detect test environment - pytest, doctest, unittest, or regular execution
 Project-URL: Homepage, https://github.com/bitranox/lib_detect_testenv
 Project-URL: Repository, https://github.com/bitranox/lib_detect_testenv.git
@@ -34,10 +34,10 @@ Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
 Requires-Dist: pytest<9,>=8.4.2; (python_version < '3.10') and extra == 'dev'
 Requires-Dist: pytest>=9.1.1; (python_version >= '3.10') and extra == 'dev'
 Requires-Dist: rtoml>=0.13.0; extra == 'dev'
-Requires-Dist: ruff>=0.16.0; extra == 'dev'
+Requires-Dist: ruff>=0.16.1; extra == 'dev'
 Requires-Dist: setuptools>=83.0.0; extra == 'dev'
 Requires-Dist: textual>=8.2.8; extra == 'dev'
-Requires-Dist: twine>=6.2.0; extra == 'dev'
+Requires-Dist: twine>=7.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # lib_detect_testenv

{lib_detect_testenv-3.0.3 → lib_detect_testenv-3.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lib_detect_testenv"
-version = "3.0.3"
+version = "3.0.4"
 description = "Detect test environment - pytest, doctest, unittest, or regular execution"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -33,14 +33,14 @@ dev = [
   "pytest>=8.4.2,<9; python_version<'3.10'",
   "pytest>=9.1.1; python_version>='3.10'",
   "pytest-cov>=7.1.0",
-  "ruff>=0.16.0",
+  "ruff>=0.16.1",
   "pyright[nodejs]>=1.1.411",
   "bandit>=1.8.6,<1.9; python_version<'3.10'",
   "bandit>=1.9.4; python_version>='3.10'",
   # 1.5.1 was yanked upstream (unintended breaking changes), so 1.5.0 is the newest usable
   # release; a >=1.5.1 floor has ZERO candidates and makes this extra unresolvable.
   "build>=1.5.0",
-  "twine>=6.2.0",
+  "twine>=7.0.0",
   # codecov-cli is disabled, not dropped: it requires click<8.3.0, which drags click back to
   # 8.2.1 - the version with CVE-2026-7246 (command injection in click.edit(), fixed in 8.3.3).
   # Nothing else here caps click, so with this line active the audit gate goes red on every

{lib_detect_testenv-3.0.3 → lib_detect_testenv-3.0.4}/src/lib_detect_testenv/__init__conf__.py

@@ -26,7 +26,7 @@ name = "lib_detect_testenv"
 #: Human-readable summary shown in CLI help output.
 title = "Detect test environment - pytest, doctest, unittest, or regular execution"
 #: Current release version pulled from ``pyproject.toml`` by automation.
-version = "3.0.3"
+version = "3.0.4"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/lib_detect_testenv"
 #: Author attribution surfaced in CLI output.

{lib_detect_testenv-3.0.3 → lib_detect_testenv-3.0.4}/src/lib_detect_testenv/cli.py

@@ -46,6 +46,7 @@ from .lib_detect_testenv import (
     is_setup_test_active,
     is_testenv_active,
 )
+from .safe_console import safe_stream
 from .typed_click import option, version_option
 
 if TYPE_CHECKING:
@@ -55,7 +56,7 @@ if TYPE_CHECKING:
 CLICK_CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
 
 #: Console for rich output
-console = Console()
+console = Console(file=safe_stream())
 
 
 @click.group(

lib_detect_testenv-3.0.4/src/lib_detect_testenv/safe_console.py

@@ -0,0 +1,213 @@
+"""Encode-safe console output.
+
+Purpose
+-------
+Wraps :func:`click.echo` so a console whose codepage cannot represent a glyph
+degrades that glyph instead of aborting the command.
+
+Why
+---
+Console output is a sink with an encoding the program does not choose. Python
+hands stdout to a Windows console at codepage 1252 with ``errors="strict"``, so
+writing ``✓`` raises ``UnicodeEncodeError: 'charmap' codec can't encode
+character '\\u2713'`` and the command exits non-zero -- after its real work has
+already succeeded, which is the part that misleads. ``click.echo`` does not
+protect against this; the exception propagates.
+
+Degrading at the SINK keeps the glyphs where they are wanted: an email body or
+a UTF-8 terminal still receives ``✓``, and only a stream that genuinely cannot
+encode it sees ``[OK]``. Callers therefore write the glyph they mean and never
+branch on the platform.
+
+Contents
+--------
+* :data:`ASCII_FALLBACKS` - the glyph-to-ASCII map
+* :func:`ascii_fallback` - transliterate text for a target encoding
+* :func:`encode_safe` - degrade text only when the encoding rejects it
+* :func:`echo` - the :func:`click.echo` replacement every module uses
+* :func:`safe_stream` - the same protection for a writer this module does not
+  own, such as the one a :class:`rich.console.Console` writes through
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import IO, Any, Final, TextIO
+
+import rich_click as click
+
+ASCII_FALLBACKS: Final[dict[str, str]] = {
+    "✓": "[OK]",  # check mark
+    "✔": "[OK]",  # heavy check mark
+    "✅": "[OK]",  # white heavy check mark
+    "✗": "[X]",  # ballot X
+    "✘": "[X]",  # heavy ballot X
+    "❌": "[X]",  # cross mark
+    "⚠": "[!]",  # warning sign
+    "️": "",  # variation selector 16, trails an emoji glyph and carries no text
+    "•": "-",  # bullet
+    "≥": ">=",
+    "≤": "<=",
+    "→": "->",
+    "←": "<-",
+    # The quotation marks are spelled as escapes on purpose: written literally
+    # they are indistinguishable from ASCII ' and " in most editors, which is
+    # exactly the confusion ruff's RUF001 exists to flag.
+    "\u2018": "'",  # left single quotation mark
+    "\u2019": "'",  # right single quotation mark
+    "\u201c": '"',  # left double quotation mark
+    "\u201d": '"',  # right double quotation mark
+    "…": "...",
+}
+
+#: Encodings that represent every code point, so the check can be skipped.
+_UNIVERSAL_ENCODINGS: Final[frozenset[str]] = frozenset({"utf-8", "utf8", "utf-16", "utf16", "utf-32", "utf32"})
+
+
+def _stream_encoding(file: IO[Any] | None) -> str | None:
+    """Return the target stream's encoding, or None when it cannot be determined.
+
+    An unknown encoding means the caller gets the original text: guessing would
+    degrade output that may well have been fine.
+    """
+    stream = file if file is not None else click.get_text_stream("stdout")
+    encoding = getattr(stream, "encoding", None)
+    return encoding if isinstance(encoding, str) else None
+
+
+def ascii_fallback(text: str, encoding: str) -> str:
+    """Rewrite `text` so it survives `encoding`.
+
+    Known glyphs become their ASCII equivalent from :data:`ASCII_FALLBACKS`;
+    anything else the codec still cannot represent becomes ``?``. Text the
+    encoding already accepts is returned unchanged.
+
+    Parameters
+    ----------
+    text:
+        The message as the caller wrote it.
+    encoding:
+        The target stream's encoding, e.g. ``"cp1252"``.
+
+    Returns
+    -------
+    str
+        A string that :meth:`str.encode` accepts for `encoding`.
+    """
+    mapped = "".join(ASCII_FALLBACKS.get(character, character) for character in text)
+    return mapped.encode(encoding, errors="replace").decode(encoding)
+
+
+def encode_safe(text: str, encoding: str | None) -> str:
+    """Return `text` if `encoding` accepts it, else its ASCII fallback.
+
+    The check runs BEFORE the write on purpose. Writing first and catching
+    ``UnicodeEncodeError`` would leave the already-encoded prefix on the stream,
+    so the retry would duplicate it.
+    """
+    if encoding is None or encoding.lower() in _UNIVERSAL_ENCODINGS:
+        return text
+    try:
+        text.encode(encoding)
+    except UnicodeEncodeError:
+        return ascii_fallback(text, encoding)
+    return text
+
+
+def echo(message: object = "", *, file: IO[Any] | None = None, err: bool = False, nl: bool = True) -> None:
+    """Write `message` to the console, degrading anything it cannot encode.
+
+    Drop-in for :func:`click.echo` for the arguments this project uses.
+
+    Parameters
+    ----------
+    message:
+        The text to write. Non-string values are stringified as click does.
+    file:
+        Target stream. Defaults to click's stdout (or stderr when `err`).
+    err:
+        Write to stderr instead of stdout.
+    nl:
+        Append a newline.
+
+    Side Effects
+    ------------
+    Writes to the given stream.
+    """
+    text = message if isinstance(message, str) else str(message)
+    target = file if file is not None else click.get_text_stream("stderr" if err else "stdout")
+    click.echo(encode_safe(text, _stream_encoding(target)), file=target, nl=nl)
+
+
+class _SafeWriter:
+    """A text stream that degrades what the wrapped stream cannot encode.
+
+    Why
+        Rich renders through a writer this module does not control, and it
+        raises the same ``UnicodeEncodeError`` on a legacy codepage rather than
+        substituting. Wrapping the writer applies the fallback to every segment
+        rich emits without rich needing to know.
+
+        With no explicit stream the target is resolved at WRITE time, not at
+        construction. A module-level ``Console(file=safe_stream())`` built at
+        import would otherwise capture the interpreter's original stdout, and
+        anything that later swaps ``sys.stdout`` - click's ``CliRunner``,
+        ``contextlib.redirect_stdout``, pytest's capture - would be bypassed
+        and its buffer would come back empty.
+    """
+
+    def __init__(self, stream: TextIO | None) -> None:
+        self._stream = stream
+
+    def _target(self) -> TextIO:
+        return self._stream if self._stream is not None else sys.stdout
+
+    def write(self, text: str) -> int:
+        """Write `text`, degrading anything the current target cannot encode."""
+        target = self._target()
+        encoding = getattr(target, "encoding", None)
+        return target.write(encode_safe(text, encoding if isinstance(encoding, str) else None))
+
+    def flush(self) -> None:
+        """Flush the current target."""
+        self._target().flush()
+
+    def isatty(self) -> bool:
+        """Report the target's tty-ness, so rich keeps its styling."""
+        return self._target().isatty()
+
+    @property
+    def encoding(self) -> str | None:
+        """Expose the target's encoding; rich inspects it."""
+        encoding = getattr(self._target(), "encoding", None)
+        return encoding if isinstance(encoding, str) else None
+
+
+def safe_stream(stream: TextIO | None = None) -> Any:  # rich accepts any writer with this shape
+    """Wrap a stream so unencodable text degrades instead of raising.
+
+    Use for a writer handed to a third-party renderer. For this project's own
+    output use :func:`echo` instead.
+
+    Parameters
+    ----------
+    stream:
+        The destination text stream. Omit it (or pass None) to follow
+        ``sys.stdout`` as it is at each write, which is what a module-level
+        renderer needs so test harnesses can still capture the output.
+
+    Returns
+    -------
+    Any
+        A writer with ``write``/``flush``/``isatty``/``encoding``.
+    """
+    return _SafeWriter(stream)
+
+
+__all__ = [
+    "ASCII_FALLBACKS",
+    "ascii_fallback",
+    "echo",
+    "encode_safe",
+    "safe_stream",
+]

lib_detect_testenv-3.0.4/tests/test_safe_console.py

@@ -0,0 +1,113 @@
+"""Tests for the encode-safe console adapter.
+
+These pin the behaviour that a legacy-codepage console (the Windows default,
+cp1252) must never turn a successful command into a crash, and the guard that
+keeps the next output line someone adds covered by construction.
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+import pytest
+from rich.console import Console
+
+from lib_detect_testenv import safe_console
+
+PKG = Path(__file__).resolve().parent.parent / "src" / "lib_detect_testenv"
+
+
+def _cp1252_stream() -> io.TextIOWrapper:
+    """Build the stream shape a Windows cp1252 console hands to Python."""
+    return io.TextIOWrapper(io.BytesIO(), encoding="cp1252", errors="strict", newline="")
+
+
+def _read_back(stream: io.TextIOWrapper) -> str:
+    stream.flush()
+    buffer = stream.buffer
+    assert isinstance(buffer, io.BytesIO)
+    return buffer.getvalue().decode("cp1252")
+
+
+class TestEchoOnALegacyCodepage:
+    """A cp1252 console must degrade the character, not raise."""
+
+    def test_check_mark_does_not_raise(self) -> None:
+        stream = _cp1252_stream()
+        safe_console.echo("\u2713 done", file=stream)
+        assert "[OK]" in _read_back(stream)
+
+    @pytest.mark.parametrize(
+        ("glyph", "expected"),
+        [("\u2713", "[OK]"), ("\u2717", "[X]"), ("\u26a0", "[!]"), ("\u2265", ">="), ("\u2192", "->")],
+    )
+    def test_a_character_cp1252_lacks_degrades_to_its_ascii_form(self, glyph: str, expected: str) -> None:
+        stream = _cp1252_stream()
+        safe_console.echo(f"{glyph} status", file=stream)
+        assert expected in _read_back(stream)
+
+    @pytest.mark.parametrize("glyph", ["\u2022", "\u2026", "\u2019"])
+    def test_a_character_cp1252_has_is_left_alone(self, glyph: str) -> None:
+        """Degrade only what the stream cannot take; cp1252 has these."""
+        stream = _cp1252_stream()
+        safe_console.echo(f"{glyph} status", file=stream)
+        assert glyph in _read_back(stream)
+
+    def test_an_unmapped_character_is_replaced_rather_than_raising(self) -> None:
+        stream = _cp1252_stream()
+        safe_console.echo("name \u4e2d\u6587 here", file=stream)
+        assert "name" in _read_back(stream)
+
+    def test_the_message_is_written_exactly_once(self) -> None:
+        """A retry-after-failure would emit the surviving prefix twice."""
+        stream = _cp1252_stream()
+        safe_console.echo("\n\u2713 done", file=stream)
+        assert _read_back(stream).count("done") == 1
+
+
+class TestEchoOnAUtf8Console:
+    """The common case must be untouched: the character survives verbatim."""
+
+    def test_character_is_preserved(self) -> None:
+        stream = io.TextIOWrapper(io.BytesIO(), encoding="utf-8", errors="strict", newline="")
+        safe_console.echo("\u2713 done", file=stream)
+        stream.flush()
+        buffer = stream.buffer
+        assert isinstance(buffer, io.BytesIO)
+        assert "\u2713" in buffer.getvalue().decode("utf-8")
+
+
+class TestSafeStreamProtectsRich:
+    """Rich raises on a legacy codepage too; it renders through its own writer."""
+
+    def test_rich_output_degrades_instead_of_raising(self) -> None:
+        stream = _cp1252_stream()
+        Console(file=safe_console.safe_stream(stream), legacy_windows=False, width=80).print("check \u2713 done \u2265 90%")
+        written = _read_back(stream)
+        assert "[OK]" in written
+        assert ">= 90%" in written
+
+
+class TestNoModuleBypassesTheAdapter:
+    """The guard that keeps this fixed for the next output line someone adds."""
+
+    def test_no_module_calls_click_echo_directly(self) -> None:
+        offenders = [
+            f"{path.relative_to(PKG)}:{number}"
+            for path in sorted(PKG.rglob("*.py"))
+            if path.name != "safe_console.py"
+            for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1)
+            if "click.echo(" in line
+        ]
+        assert not offenders, f"these call click.echo directly and will crash on a cp1252 console; use safe_console.echo instead: {offenders}"
+
+    def test_no_module_builds_an_unwrapped_rich_console_on_stdout(self) -> None:
+        offenders = [
+            f"{path.relative_to(PKG)}:{number}"
+            for path in sorted(PKG.rglob("*.py"))
+            if path.name != "safe_console.py"
+            for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1)
+            if "Console(file=sys.stdout" in line
+        ]
+        assert not offenders, f"wrap the writer with safe_console.safe_stream(sys.stdout): {offenders}"