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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: provide-testkit
-Version: 0.5.2
+Version: 0.5.3
 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.3/VERSION

@@ -0,0 +1 @@
+0.5.3

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

@@ -0,0 +1,144 @@
+#
+# 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, so the module is built to retire itself rather than to
+be remembered. Installing drives a real capture through swap, suspend and
+resume, and patches only a pytest that loses the swap -- one that keeps it is
+left alone, by whatever route it came to keep it. A pytest that no longer has
+the class costs the fix and nothing else: the import is asked for inside the
+call rather than at module scope, so a reshaped capture module cannot take the
+plugin, and every suite that loads it, down with it.
+"""
+
+from __future__ import annotations
+
+import io
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    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"
+_STDOUT_FD = 1
+
+
+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 _capture_classes() -> tuple[Any, type] | None:
+    """The class to patch and the one to probe, or ``None`` from a pytest without them.
+
+    ``SysCaptureBase`` carries the two methods for every capture that reaches
+    ``sys``; ``SysCapture`` is the one that can be driven. Asking for them here
+    rather than at import is what keeps a renamed or removed class a lost fix
+    instead of an ``ImportError`` raised while the plugin is loading.
+    """
+    try:
+        from _pytest.capture import SysCapture, SysCaptureBase
+    except (ImportError, AttributeError):
+        return None
+    return SysCaptureBase, SysCapture
+
+
+def _drops_a_swap(probe_class: type) -> bool:
+    """Whether this pytest loses a stream installed after capturing started.
+
+    The question is behavioural, so the answer is measured rather than read off
+    a version: start a capture, swap the stream, cycle suspend and resume, and
+    see which stream is left standing. A pytest that keeps the swap wants
+    nothing from this module, and a version number cannot say which pytest that
+    is -- a backport, a fork or a vendored copy all answer here for themselves.
+
+    A probe that cannot be driven at all -- a capture reshaped past recognition
+    -- reports no defect. Patching a class whose behaviour could not be
+    established is how a fix becomes the outage.
+    """
+    saved = sys.stdout
+    try:
+        probe = probe_class(_STDOUT_FD)
+        probe.start()
+        try:
+            swapped_in = io.StringIO()
+            sys.stdout = swapped_in
+            probe.suspend()
+            probe.resume()
+            return sys.stdout is not swapped_in
+        finally:
+            probe.done()
+    except Exception:
+        return False
+    finally:
+        sys.stdout = saved
+
+
+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 -- a pytest that already keeps the swap, one whose
+    methods belong to another patcher, and one this module cannot recognise are
+    all cases where doing nothing is the whole job.
+    """
+    classes = _capture_classes()
+    if classes is None:
+        return False
+    patch_target, probe_class = classes
+
+    # Read the marker off the class itself. A subclass inherits it, and asking
+    # through inheritance would report a fix that is not on the class in hand.
+    if _INSTALLED_MARKER in patch_target.__dict__:
+        return False
+    if any(getattr(patch_target, name).__module__ != "_pytest.capture" for name in ("suspend", "resume")):
+        return False
+    if not _drops_a_swap(probe_class):
+        return False
+
+    patch_target.suspend = _suspend
+    patch_target.resume = _resume
+    setattr(patch_target, _INSTALLED_MARKER, True)
+    return True

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: provide-testkit
-Version: 0.5.2
+Version: 0.5.3
 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 → provide_testkit-0.5.3}/tests/test_capture_stream_swap.py

@@ -22,6 +22,7 @@ import sys
 from _pytest.capture import SysCapture
 import pytest
 
+from provide.testkit import _capture
 from provide.testkit._capture import install_capture_swap_fix
 
 STDOUT_FD = 1
@@ -140,3 +141,89 @@ def test_the_same_run_loses_its_output_without_this_plugin(pytester: pytest.Pyte
     result = pytester.runpytest_subprocess("-o", "log_cli=true", "-p", "no:provide_testkit")
 
     result.assert_outcomes(failed=1)
+
+
+class _FixedSysCapture(SysCapture):
+    """A pytest whose capture hands back the stream that was in place."""
+
+    def suspend(self) -> None:
+        self._assert_state("suspend", ("started", "suspended"))
+        if self._state == "started":
+            self._seen = getattr(sys, self.name)
+        setattr(sys, self.name, self._old)
+        self._state = "suspended"
+
+    def resume(self) -> None:
+        self._assert_state("resume", ("started", "suspended"))
+        if self._state == "started":
+            return
+        setattr(sys, self.name, getattr(self, "_seen", self.tmpfile))
+        self._state = "started"
+
+
+class _UnfixedSysCapture(SysCapture):
+    """Pytest as shipped: resume reinstates the stream capture installed."""
+
+    def suspend(self) -> None:
+        self._assert_state("suspend", ("started", "suspended"))
+        setattr(sys, self.name, self._old)
+        self._state = "suspended"
+
+    def resume(self) -> None:
+        self._assert_state("resume", ("started", "suspended"))
+        if self._state == "started":
+            return
+        setattr(sys, self.name, self.tmpfile)
+        self._state = "started"
+
+
+# Both stand-ins answer for pytest itself, so they must claim the origin the
+# install check reads -- a class whose methods came from anywhere else is a
+# different patcher, and declining that is a separate rule.
+for _stand_in in (_FixedSysCapture, _UnfixedSysCapture):
+    _stand_in.suspend.__module__ = "_pytest.capture"
+    _stand_in.resume.__module__ = "_pytest.capture"
+
+
+def test_the_fix_is_declined_when_pytest_already_preserves_the_swap(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The exit route: a pytest that fixed this upstream is left alone."""
+    monkeypatch.setattr(_capture, "_capture_classes", lambda: (_FixedSysCapture, _FixedSysCapture))
+
+    installed = install_capture_swap_fix()
+
+    assert installed is False
+    assert _FixedSysCapture.suspend.__qualname__ == "_FixedSysCapture.suspend"
+
+
+def test_the_fix_is_installed_when_pytest_still_drops_the_swap(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The probe answers by behaviour, so it must still say yes to today's pytest."""
+    monkeypatch.setattr(_capture, "_capture_classes", lambda: (_UnfixedSysCapture, _UnfixedSysCapture))
+
+    installed = install_capture_swap_fix()
+
+    assert installed is True
+    assert _UnfixedSysCapture.suspend is _capture._suspend
+
+
+def test_a_pytest_without_the_class_leaves_the_plugin_importable(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A reshaped pytest must cost the fix, not every suite that loads the plugin."""
+    monkeypatch.setattr(_capture, "_capture_classes", lambda: None)
+
+    assert install_capture_swap_fix() is False
+
+
+@pytest.mark.usefixtures("stdout_restored")
+def test_the_probe_gives_back_the_stream_it_found(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Deciding whether to patch runs a real capture; it must leave no trace."""
+    monkeypatch.setattr(_capture, "_capture_classes", lambda: (_UnfixedSysCapture, _UnfixedSysCapture))
+    before = sys.stdout
+
+    install_capture_swap_fix()
+
+    assert sys.stdout is before

provide_testkit-0.5.2/VERSION

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

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

@@ -1,81 +0,0 @@
-#
-# 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