Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Wraps callables to capture stdout, stderr, exceptions and the return

Project description

Build Status

Method Capture

Wraps callables to capture stdout, stderr, exceptions and the return.


This library was created to assist in the testing of Python code, where return values and exceptions are important, in addition to what is written to stdout and stderr. It allows for a callable to be ran without the caller being concerned with how important outputs are captured.

An example use is when writing common code to test both a Python interface and a corresponding CLI (tested by invoking main). A common test procedure - which may involve a complex setup and tear down - can be ran using the different interfaces and return results that encapsulate the outputs, without concern over the form they take (e.g. the Python interface may have returned True on success but the CLI may have called exit(0), with raises a SystemExit exception).

Other alternatives exist for capturing stdout and stderr but none also handle exceptions.



from capturewrap import CaptureWrapBuilder

builder = CaptureWrapBuilder(capture_stdout=True, capture_stderr=True, capture_exceptions=True)
wrapped =

result = wrapped(*args, **kwargs)
print(f"stdout: {result.stdout}")
print(f"stderr: {result.stderr}")
print(f"return_value: {result.return_value}")
print(f"exception: {result.exception}")

Note: if an exception is captured, return_value will be None.

Custom Exception Capture

It may be desirable to capture only some exceptions and leave others to get raised as normal. To do this with CaptureWrapBuilder, set capture_exceptions as a function that takes the exception as the first argument and returns back a boolean value to indicate if the exception should be captured. e.g.

from capturewrap import CaptureWrapBuilder

builder = CaptureWrapBuilder(capture_exceptions=lambda e: isinstance(e, SystemExit) and e.code == 0)
wrapped =

print(wrapped(0))   # {"exception": ["SystemExit: 0\n"]}
print(wrapped(1))   # Raises exception


  • Python >= 3.6


Stable releases can be installed via PyPI:

$ pip install capturewrap

Bleeding edge versions can be installed directly from GitHub:

$ pip install git+$commitOrBranch#egg=capturewrap


This implementation captures stdout and stdin using `redirect_stdout <>`__ and `redirect_stderr <>`__, which were added to the standard library in Python 3.5.


  • iocapture: older solution, replaces sys.stdout and sys.stderr with capturing methods.
  • capturer: complex solution that works at lower level to intercept subprocess stdout and stderr using a pseudo terminal.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for capturewrap, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size capturewrap-1.1.0.tar.gz (6.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page