Skip to content

capture ¤

Enumeration of possible output captures.

Capture ¤

Bases: Enum

An enum to store the different possible output types.

cast classmethod ¤

cast(value: str | bool | Capture | None) -> Capture

Cast a value to an actual Capture enumeration value.

Parameters:

Returns:

  • Capture –

    A Capture enumeration value.

Source code in src/failprint/capture.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@classmethod
def cast(cls, value: str | bool | Capture | None) -> Capture:
    """Cast a value to an actual Capture enumeration value.

    Arguments:
        value: The value to cast.

    Returns:
        A Capture enumeration value.
    """
    if value is None:
        return cls.BOTH
    if value is True:
        return cls.BOTH
    if value is False:
        return cls.NONE
    if isinstance(value, cls):
        return value
    # consider it's a string
    # let potential errors bubble up
    return cls(value)

here ¤

here(stdin: str | None = None) -> Iterator[CaptureManager]

Context manager to capture standard output/error.

Parameters:

  • stdin (str | None, default: None ) –

    Optional input.

Yields:

Examples:

>>> def print_things() -> None:
...     print("1")
...     sys.stderr.write("2\n")
...     os.system("echo 3")
...     subprocess.run(["sh", "-c", "echo 4 >&2"])
>>> with Capture.BOTH.here() as captured:
...     print_things()
... print(captured)
1
2
3
4
Source code in src/failprint/capture.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@contextmanager
def here(self, stdin: str | None = None) -> Iterator[CaptureManager]:
    """Context manager to capture standard output/error.

    Parameters:
        stdin: Optional input.

    Yields:
        A lazy string with the captured contents.

    Examples:
        >>> def print_things() -> None:
        ...     print("1")
        ...     sys.stderr.write("2\\n")
        ...     os.system("echo 3")
        ...     subprocess.run(["sh", "-c", "echo 4 >&2"])
        >>> with Capture.BOTH.here() as captured:
        ...     print_things()
        ... print(captured)
        1
        2
        3
        4
    """  # noqa: D301
    with CaptureManager(self, stdin=stdin) as captured:
        yield captured

CaptureManager ¤

CaptureManager(
    capture: Capture = Capture.BOTH,
    stdin: str | None = None,
)

Context manager to capture standard output and error at the file descriptor level.

Usable directly through Capture.here.

Examples:

>>> def print_things() -> None:
...     print("1")
...     sys.stderr.write("2\n")
...     os.system("echo 3")
...     subprocess.run(["sh", "-c", "echo 4 >&2"])
>>> with CaptureManager(Capture.BOTH) as captured:
...     print_things()
... print(captured)
1
2
3
4

Parameters:

  • capture (Capture, default: BOTH ) –

    What to capture.

  • stdin (str | None, default: None ) –

    Optional input.

Source code in src/failprint/capture.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def __init__(self, capture: Capture = Capture.BOTH, stdin: str | None = None) -> None:
    """Initialize the context manager.

    Parameters:
        capture: What to capture.
        stdin: Optional input.
    """
    self._temp_file: IO[str] | None = None
    self._capture = capture
    self._devnull: TextIO | None = None
    self._stdin = stdin
    self._saved_stdin: TextIO | None = None
    self._stdout_fd: int = -1
    self._stderr_fd: int = -1
    self._saved_stdout_fd: int = -1
    self._saved_stderr_fd: int = -1
    self._output: str | None = None

output property ¤

output: str

Captured output.

Raises:

  • RuntimeError –

    When accessing captured output before exiting the context manager.