hbutils.testing.capture.output

Utilities for capturing, redirecting, and disabling standard output streams.

This module provides context managers that make it easy to capture or suppress output written to sys.stdout and sys.stderr during a block of code. It supports both in-memory capturing (via io.StringIO) and file-based capturing (via temporary files), as well as complete suppression by redirecting output to the platform’s null device.

The module exposes the following public components:

• OutputCaptureResult - Thread-safe container for captured output

• capture_output() - Capture output within a with block

• disable_output() - Suppress output within a with block

Example:

>>> import sys
>>> from hbutils.testing.capture.output import capture_output, disable_output
>>>
>>> with capture_output() as result:
...     print("hello stdout")
...     print("hello stderr", file=sys.stderr)
...
>>> result.stdout
'hello stdout\n'
>>> result.stderr
'hello stderr\n'
>>>
>>> with disable_output():
...     print("this will not appear")

Note

When capturing output in memory (mem=True), io.StringIO is used. This object does not provide fileno(), which may affect libraries that require a real file descriptor (e.g., subprocess.run()).

__all__

hbutils.testing.capture.output.__all__ = ['OutputCaptureResult', 'capture_output', 'disable_output']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

OutputCaptureResult

class hbutils.testing.capture.output.OutputCaptureResult

Thread-safe container for captured stdout and stderr content.

This class stores the captured output from capture_output() and allows safe access from multiple threads. Accessing stdout or stderr before the capture context has exited will block until the capture is done.

Example:

>>> import sys
>>> from hbutils.testing.capture.output import capture_output
>>> with capture_output() as result:
...     print("x")
...     print("y", file=sys.stderr)
...
>>> result.stdout
'x\n'
>>> result.stderr
'y\n'

Warning

Accessing stdout or stderr before the capture context is finished will block due to internal locking.

__init__() → None

Initialize an empty capture result.

The instance starts with None values for both stdout and stderr and uses an acquired lock to block access until results are set.

put_result(stdout: str | None, stderr: str | None) → None

Store the captured stdout and stderr results.

Parameters:

• stdout (Optional[str]) – Captured stdout content.

• stderr (Optional[str]) – Captured stderr content.

property stderr: str | None

Captured stderr content.

Returns:

The captured stderr text, or None if capture failed.

Return type:

Optional[str]

Note

Do not access this property before the capture_output() context has exited, or the call will block.

property stdout: str | None

Captured stdout content.

Returns:

The captured stdout text, or None if capture failed.

Return type:

Optional[str]

Note

Do not access this property before the capture_output() context has exited, or the call will block.

capture_output

hbutils.testing.capture.output.capture_output(mem: bool = False) → ContextManager[OutputCaptureResult]

Capture output to sys.stdout and sys.stderr within a with block.

When mem is False (default), output is captured to temporary files. When mem is True, output is captured using in-memory io.StringIO buffers.

Parameters:

mem (bool) – Whether to capture output in memory, defaults to False.

Returns:

A context manager yielding an OutputCaptureResult.

Return type:

ContextManager[OutputCaptureResult]

Examples::

>>> from hbutils.testing import capture_output
>>> import sys
>>>
>>> with capture_output() as r:
...     print('this is stdout')
...     print('this is stderr', file=sys.stderr)
...
>>> r.stdout
'this is stdout\n'
>>> r.stderr
'this is stderr\n'

Note

When mem is set to True, io.StringIO is used, which does not provide fileno(). Use mem=False for compatibility with subprocess-related operations.

disable_output

hbutils.testing.capture.output.disable_output(encoding: str = 'utf-8') → ContextManager[None]

Disable all output to sys.stdout and sys.stderr within a with block.

All output during the block is redirected to the system’s null device (e.g., /dev/null on Unix-like systems or NUL on Windows).

Parameters:

encoding (str) – Encoding used for the null device, defaults to 'utf-8'.

Returns:

A context manager that suppresses all output.

Return type:

ContextManager[None]

Examples::

>>> import sys
>>> from hbutils.testing import disable_output
>>>
>>> with disable_output():
...     print('this is stdout')
...     print('this is stderr', file=sys.stderr)