provide-testkit 0.5.0__tar.gz → 0.5.2__tar.gz

{provide_testkit-0.5.0/src/provide_testkit.egg-info → provide_testkit-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: provide-testkit
-Version: 0.5.0
+Version: 0.5.2
 Summary: Testing utilities and fixtures for the provide ecosystem.
 Author-email: Tim Perkins <code@tim.life>
 Maintainer-email: "provide.io" <code@provide.io>

provide_testkit-0.5.2/VERSION

@@ -0,0 +1 @@
+0.5.2

provide_testkit-0.5.2/src/provide/testkit/_capture.py

@@ -0,0 +1,81 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) provide.io llc. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+
+"""Capture that gives back the stream it took, not the one it remembers.
+
+``SysCaptureBase.suspend`` hands ``sys.stdout`` back to the stream pytest saved
+before capture started, and ``resume`` reinstates ``tmpfile`` -- the stream
+capture installed at ``start``. Neither looks at what is actually there. A test
+that swaps the stream after capture started owns something pytest has no record
+of, so the swap is discarded on the first suspend and every write after it lands
+in pytest's buffer instead of the caller's.
+
+``log_cli = true`` makes that ordinary: pytest's live-log handler sits on the
+root logger and suspends global capture around each record. One log line emitted
+from inside ``CliRunner.invoke`` -- from any library, at any depth -- leaves
+``result.output`` empty while the text itself is real and lands in pytest's own
+capture. ``contextlib.redirect_stdout`` and hand-rolled stream fixtures lose
+their swap the same way.
+
+The pair below remembers the stream that was in place at suspend and returns it
+at resume, which is what the two methods already claim to do. Teardown is
+untouched: ``done`` still restores the stream capture replaced, so a swap left
+behind by a test cannot outlive it.
+
+This belongs in pytest, and the tests in ``tests/test_capture_stream_swap.py``
+drive the real ``SysCapture``, so they fail loudly once pytest changes the
+methods underneath -- whether it fixes this or reshapes the class. Drop this
+module when the pytest floor carries the fix.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from _pytest.capture import SysCaptureBase
+
+__all__ = ["install_capture_swap_fix"]
+
+_INSTALLED_MARKER = "_provide_testkit_swap_safe"
+# The stream is parked on pytest's object, so the name says whose it is.
+_SWAPPED_IN = "_provide_testkit_swapped_in"
+
+
+def _suspend(self: SysCaptureBase[Any]) -> None:
+    self._assert_state("suspend", ("started", "suspended"))
+    # Suspending while suspended is legal, and the stream sitting there then is
+    # the one suspend itself installed -- not a swap worth remembering.
+    if self._state == "started":
+        setattr(self, _SWAPPED_IN, getattr(sys, self.name))
+    setattr(sys, self.name, self._old)
+    self._state = "suspended"
+
+
+def _resume(self: SysCaptureBase[Any]) -> None:
+    self._assert_state("resume", ("started", "suspended"))
+    if self._state == "started":
+        return
+    # A capture resumed without ever suspending has nothing recorded, and the
+    # stream capture installed is the right answer for it.
+    setattr(sys, self.name, getattr(self, _SWAPPED_IN, self.tmpfile))
+    self._state = "started"
+
+
+def install_capture_swap_fix() -> bool:
+    """Make pytest's stream capture preserve a swap made after it started.
+
+    Returns whether this call is the one that installed it. Declining leaves
+    pytest exactly as found: the fix is worth having, and silently layering it
+    over a patch someone else installed is not.
+    """
+    if getattr(SysCaptureBase, _INSTALLED_MARKER, False):
+        return False
+    if any(getattr(SysCaptureBase, name).__module__ != "_pytest.capture" for name in ("suspend", "resume")):
+        return False
+    SysCaptureBase.suspend = _suspend  # type: ignore[method-assign]
+    SysCaptureBase.resume = _resume  # type: ignore[method-assign]
+    setattr(SysCaptureBase, _INSTALLED_MARKER, True)
+    return True

{provide_testkit-0.5.0 → provide_testkit-0.5.2}/src/provide/testkit/_early_init.py

@@ -124,6 +124,8 @@ def _configure_structlog_for_testing() -> None:
             event_dict.pop("_foundation_level_hint", None)
             return event_dict
 
+        from provide.testkit._streams import unicode_safe
+
         structlog.configure(
             processors=[
                 structlog.processors.TimeStamper(fmt="iso"),
@@ -134,7 +136,7 @@ def _configure_structlog_for_testing() -> None:
             wrapper_class=structlog.BoundLogger,
             context_class=dict,
             # Use stderr instead of stdout to avoid polluting pytest-xdist pipe communication
-            logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+            logger_factory=structlog.PrintLoggerFactory(file=unicode_safe(sys.stderr)),
             cache_logger_on_first_use=False,  # Disable caching for test isolation
         )
     except Exception:

provide_testkit-0.5.2/src/provide/testkit/_streams.py

@@ -0,0 +1,73 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) provide.io llc. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+
+"""Keeping test logging off the path where a console encoding can raise.
+
+This module deliberately imports nothing from Foundation. The plugin that uses
+it configures structlog before any Foundation module is imported, and reaching
+for Foundation here would defeat that ordering.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["unicode_safe"]
+
+_UTF8_NAMES = frozenset({"utf8", "utf_8", "u8", "cp65001"})
+
+
+class _UnicodeSafeStream:
+    """A stream whose writes cannot fail on a character it cannot encode.
+
+    The replacement is written through the same text layer rather than the byte
+    layer underneath, so pytest's capture of that stream still sees the output.
+
+    Everything other than `write` is delegated, so the wrapped stream answers
+    for its own `isatty`, `flush` and `encoding`.
+    """
+
+    # structlog takes a weak reference to the file it logs through, so the
+    # slotted class has to allow one.
+    __slots__ = ("__weakref__", "_stream")
+
+    def __init__(self, stream: Any) -> None:
+        self._stream = stream
+
+    def write(self, text: str) -> int:
+        try:
+            written = self._stream.write(text)
+        except UnicodeEncodeError:
+            encoding = getattr(self._stream, "encoding", None) or "ascii"
+            # backslashreplace names the character (\U0001f40d) where replace
+            # would erase it ('?'), and a test log line is read by a person.
+            safe = text.encode(encoding, "backslashreplace").decode(encoding, "replace")
+            self._stream.write(safe)
+            return len(text)
+        # colorama's Windows wrapper returns None rather than a count, so the
+        # length of what was handed over stands in for it.
+        return written if isinstance(written, int) else len(text)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._stream, name)
+
+
+def _encodes_everything(stream: Any) -> bool:
+    """Whether the stream takes any str without raising."""
+    encoding = getattr(stream, "encoding", None)
+    if not isinstance(encoding, str):
+        # StringIO and friends hold str directly.
+        return True
+    return encoding.lower().replace("-", "").replace("_", "") in _UTF8_NAMES
+
+
+def unicode_safe(stream: Any) -> Any:
+    """The stream, wrapped only if a character could make it raise.
+
+    Idempotent, so a stream reconfigured repeatedly does not accumulate proxies.
+    """
+    if isinstance(stream, _UnicodeSafeStream) or _encodes_everything(stream):
+        return stream
+    return _UnicodeSafeStream(stream)

{provide_testkit-0.5.0 → provide_testkit-0.5.2}/src/provide/testkit/pytest_plugin.py

@@ -29,6 +29,9 @@ import sys
 
 import structlog
 
+from provide.testkit._capture import install_capture_swap_fix
+from provide.testkit._streams import unicode_safe
+
 # Configure structlog with test-safe defaults BEFORE Foundation imports.
 # This ensures that even if Foundation's get_logger() falls back to structlog.get_logger()
 # during circular import resolution, the returned loggers will have proper configuration
@@ -50,17 +53,28 @@ def _strip_foundation_context(
     return event_dict
 
 
-structlog.configure(
-    processors=[
-        structlog.processors.TimeStamper(fmt="iso"),
-        _strip_foundation_context,  # type: ignore[list-item]
-        structlog.dev.ConsoleRenderer(),
-    ],
-    wrapper_class=structlog.BoundLogger,
-    context_class=dict,
-    logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
-    cache_logger_on_first_use=False,  # Disable caching for test isolation
-)
+def _configure_test_structlog() -> None:
+    """Configure structlog for the test session.
+
+    The stream is read at call time and wrapped: on a legacy console this is a
+    cp1252 stream behind colorama, and a log line carrying an emoji would
+    otherwise raise UnicodeEncodeError out of the logging call and into
+    whatever the test was doing.
+    """
+    structlog.configure(
+        processors=[
+            structlog.processors.TimeStamper(fmt="iso"),
+            _strip_foundation_context,  # type: ignore[list-item]
+            structlog.dev.ConsoleRenderer(),
+        ],
+        wrapper_class=structlog.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=unicode_safe(sys.stdout)),
+        cache_logger_on_first_use=False,  # Disable caching for test isolation
+    )
+
+
+_configure_test_structlog()
 
 # Install the import hook unconditionally
 # This module is a pytest plugin (registered via pytest11 entry point) that ONLY
@@ -71,6 +85,12 @@ from provide.testkit._install_blocker import install_setproctitle_blocker  # noq
 
 install_setproctitle_blocker(force=True)
 
+# Pytest hands a suspended stream back to whatever it saved at start, so a test
+# that swaps sys.stdout after that -- CliRunner.isolation, redirect_stdout --
+# loses the swap the first time a live log record suspends capture, and its
+# output lands in pytest's buffer instead. See provide.testkit._capture.
+install_capture_swap_fix()
+
 __all__ = ["SetproctitleImportBlocker", "pytest_load_initial_conftests"]
 
 

{provide_testkit-0.5.0 → provide_testkit-0.5.2/src/provide_testkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: provide-testkit
-Version: 0.5.0
+Version: 0.5.2
 Summary: Testing utilities and fixtures for the provide ecosystem.
 Author-email: Tim Perkins <code@tim.life>
 Maintainer-email: "provide.io" <code@provide.io>

{provide_testkit-0.5.0 → provide_testkit-0.5.2}/src/provide_testkit.egg-info/SOURCES.txt

@@ -6,9 +6,11 @@ src/provide/__init__.py
 src/provide/testkit/__init__.py
 src/provide/testkit/__main__.py
 src/provide/testkit/_blocker.py
+src/provide/testkit/_capture.py
 src/provide/testkit/_early_init.py
 src/provide/testkit/_install_blocker.py
 src/provide/testkit/_install_pth.py
+src/provide/testkit/_streams.py
 src/provide/testkit/conftest.py
 src/provide/testkit/main.py
 src/provide/testkit/provide_testkit_init.pth
@@ -109,6 +111,8 @@ src/provide_testkit.egg-info/entry_points.txt
 src/provide_testkit.egg-info/requires.txt
 src/provide_testkit.egg-info/top_level.txt
 tests/test_async_fixtures.py
+tests/test_capture_stream_swap.py
 tests/test_early_init.py
 tests/test_placeholder.py
-tests/test_pth_installation.py
+tests/test_pth_installation.py
+tests/test_stream_encoding.py

provide_testkit-0.5.2/tests/test_capture_stream_swap.py

@@ -0,0 +1,142 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) provide.io llc. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+
+"""Pytest's capture must give back the stream it took, not the one it remembers.
+
+``SysCaptureBase.resume`` reinstates the stream capture installed at ``start``.
+Anything that swapped ``sys.stdout`` after that point -- ``CliRunner.isolation``,
+``redirect_stdout``, a fixture of one's own -- is dropped the first time capture
+suspends, and every write after that lands in pytest's buffer. Live logging
+(``log_cli = true``) suspends capture per record, so one log line emitted from
+inside a Click command empties ``result.output`` while the text itself is real.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+import io
+import sys
+
+from _pytest.capture import SysCapture
+import pytest
+
+from provide.testkit._capture import install_capture_swap_fix
+
+STDOUT_FD = 1
+
+
+@pytest.fixture
+def stdout_restored() -> Iterator[None]:
+    """Put ``sys.stdout`` back, however the test under it leaves things."""
+    saved = sys.stdout
+    try:
+        yield
+    finally:
+        sys.stdout = saved
+
+
+@pytest.mark.usefixtures("stdout_restored")
+def test_resume_returns_a_swap_made_after_capture_started() -> None:
+    """The case behind an empty ``CliRunner.result.output``."""
+    capture = SysCapture(STDOUT_FD)
+    capture.start()
+    swapped_in = io.StringIO()
+    sys.stdout = swapped_in
+
+    capture.suspend()
+    capture.resume()
+
+    assert sys.stdout is swapped_in
+    capture.done()
+
+
+@pytest.mark.usefixtures("stdout_restored")
+def test_resume_returns_the_capture_stream_when_nothing_swapped_it() -> None:
+    """The ordinary path stays exactly as pytest wrote it."""
+    capture = SysCapture(STDOUT_FD)
+    capture.start()
+
+    capture.suspend()
+    capture.resume()
+
+    assert sys.stdout is capture.tmpfile
+    capture.done()
+
+
+@pytest.mark.usefixtures("stdout_restored")
+def test_a_second_suspend_does_not_overwrite_the_remembered_swap() -> None:
+    """Suspending while suspended is legal, and must not record ``_old`` as the swap."""
+    capture = SysCapture(STDOUT_FD)
+    capture.start()
+    swapped_in = io.StringIO()
+    sys.stdout = swapped_in
+
+    capture.suspend()
+    capture.suspend()
+    capture.resume()
+
+    assert sys.stdout is swapped_in
+    capture.done()
+
+
+@pytest.mark.usefixtures("stdout_restored")
+def test_done_restores_the_stream_capture_replaced() -> None:
+    """Teardown belongs to pytest: a foreign swap does not outlive the capture."""
+    original = sys.stdout
+    capture = SysCapture(STDOUT_FD)
+    capture.start()
+    sys.stdout = io.StringIO()
+
+    capture.done()
+
+    assert sys.stdout is original
+
+
+def test_installing_the_fix_again_reports_that_it_was_already_there() -> None:
+    """The plugin installs it at import; a second call must not stack a layer."""
+    assert install_capture_swap_fix() is False
+
+
+CLI_UNDER_LIVE_LOGGING = """
+import logging
+
+import click
+from click.testing import CliRunner
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    # Any library logging from inside the command does this; the record only has
+    # to reach the root logger, where live logging is listening.
+    logging.getLogger("some.library").warning("a record reaches the root logger")
+
+
+@cli.command()
+def sub() -> None:
+    click.echo("SUBCOMMAND OUTPUT")
+
+
+def test_the_runner_sees_what_the_command_printed() -> None:
+    assert CliRunner().invoke(cli, ["sub"]).output != ""
+"""
+
+
+def test_a_cli_runner_keeps_its_output_across_a_live_log_record(pytester: pytest.Pytester) -> None:
+    """The reported symptom, through the real Click and the real live-log handler."""
+    pytester.makepyfile(CLI_UNDER_LIVE_LOGGING)
+
+    result = pytester.runpytest_subprocess("-o", "log_cli=true")
+
+    result.assert_outcomes(passed=1)
+
+
+def test_the_same_run_loses_its_output_without_this_plugin(pytester: pytest.Pytester) -> None:
+    """Without this, the test above could pass for the wrong reason."""
+    pytester.makepyfile(CLI_UNDER_LIVE_LOGGING)
+
+    result = pytester.runpytest_subprocess("-o", "log_cli=true", "-p", "no:provide_testkit")
+
+    result.assert_outcomes(failed=1)

provide_testkit-0.5.2/tests/test_stream_encoding.py

@@ -0,0 +1,109 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) provide.io llc. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+
+"""Test logging must not raise on a console that cannot encode the message.
+
+The plugin configures structlog before Foundation is imported, so the stream it
+hands structlog is whatever pytest is holding at that moment. On Windows that is
+a cp1252 console behind colorama, and a log line carrying an emoji raised
+UnicodeEncodeError out of the logging call and into the test.
+"""
+
+from __future__ import annotations
+
+import io
+
+from provide.testkit._streams import unicode_safe
+
+
+class _Cp1252Stream(io.TextIOWrapper):
+    """Stands in for the Windows console pytest hands the plugin."""
+
+    def __init__(self) -> None:
+        super().__init__(io.BytesIO(), encoding="cp1252", newline="")
+
+    def written(self) -> str:
+        self.flush()
+        return self.buffer.getvalue().decode("cp1252")  # type: ignore[attr-defined]
+
+
+def test_the_stand_in_really_does_raise() -> None:
+    """Without this, every test below could pass for the wrong reason."""
+    try:
+        _Cp1252Stream().write("\U0001f40d")
+    except UnicodeEncodeError:
+        return
+    raise AssertionError("the cp1252 stand-in accepted an emoji")
+
+
+def test_an_unencodable_character_does_not_raise() -> None:
+    unicode_safe(_Cp1252Stream()).write("repo \U0001f40d state\n")
+
+
+def test_the_surrounding_text_survives() -> None:
+    stream = _Cp1252Stream()
+
+    unicode_safe(stream).write("repo \U0001f40d state\n")
+
+    written = stream.written()
+    assert "repo " in written
+    assert "state" in written
+
+
+def test_the_character_is_named_rather_than_dropped() -> None:
+    """backslashreplace keeps the emoji readable; 'replace' would give '?'."""
+    stream = _Cp1252Stream()
+
+    unicode_safe(stream).write("\U0001f40d\n")
+
+    assert "\\U0001f40d" in stream.written()
+
+
+def test_a_stream_that_can_encode_is_handed_back_unchanged() -> None:
+    stream = io.StringIO()
+
+    assert unicode_safe(stream) is stream
+
+
+def test_wrapping_is_idempotent() -> None:
+    wrapped = unicode_safe(_Cp1252Stream())
+
+    assert unicode_safe(wrapped) is wrapped
+
+
+def test_the_wrapper_delegates_what_it_does_not_define() -> None:
+    stream = _Cp1252Stream()
+
+    assert unicode_safe(stream).encoding == "cp1252"
+
+
+class _NoReturnStream:
+    """colorama's Windows wrapper: write() returns None, not a count."""
+
+    encoding = "cp1252"
+
+    def __init__(self) -> None:
+        self.text = ""
+
+    def write(self, text: str) -> None:
+        self.text += text.encode("cp1252", "strict").decode("cp1252")
+
+
+def test_a_stream_whose_write_returns_none_is_accepted() -> None:
+    """colorama returns None from write; coercing that to int raised TypeError."""
+    assert unicode_safe(_NoReturnStream()).write("plain\n") == len("plain\n")
+
+
+def test_the_plugin_configures_a_stream_that_cannot_raise(monkeypatch) -> None:
+    """The regression: the plugin handed structlog the raw console."""
+    import structlog
+
+    monkeypatch.setattr("sys.stdout", _Cp1252Stream())
+
+    import provide.testkit.pytest_plugin as plugin
+
+    plugin._configure_test_structlog()
+
+    structlog.get_config()["logger_factory"]().msg("repo \U0001f40d state")

provide_testkit-0.5.0/VERSION

@@ -1 +0,0 @@
-0.5.0