1# Wurlitzer
2
3Capture C-level stdout/stderr pipes in Python via `os.dup2`.
4
5For more details on why this is needed, please read [this blog post](https://eli.thegreenplace.net/2015/redirecting-all-kinds-of-stdout-in-python/).
6
7## Install
8
9    pip install wurlitzer
10
11## Usage
12
13Capture stdout/stderr in pipes:
14
15```python
16from wurlitzer import pipes
17
18with pipes() as (out, err):
19    call_some_c_function()
20
21stdout = out.read()
22```
23
24Capture stdout/stderr in StringIO:
25
26```python
27from io import StringIO
28from wurlitzer import pipes, STDOUT
29
30out = StringIO()
31with pipes(stdout=out, stderr=STDOUT):
32    call_some_c_function()
33
34stdout = out.getvalue()
35```
36
37Forward C-level stdout/stderr to Python sys.stdout/stderr,
38which may already be forwarded somewhere by the environment, e.g. IPython:
39
40```python
41from wurlitzer import sys_pipes
42
43with sys_pipes():
44    call_some_c_function()
45```
46
47Or even simpler, enable it as an IPython extension:
48
49```
50%load_ext wurlitzer
51```
52
53To forward all C-level output to IPython during execution.
54
55## Acknowledgments
56
57This package is based on stuff we learned with @takluyver and @karies while working on capturing output from the [Cling Kernel](https://github.com/root-mirror/cling/tree/master/tools/Jupyter/kernel) for Jupyter.
58
59## Wurlitzer?!
60
61[Wurlitzer](https://en.wikipedia.org/wiki/Wurlitzer) makes pipe organs. Get it? Pipes? Naming is hard.
62