0
# Wurlitzer
1

2
[@describes](wurlitzer)
3

4
A comprehensive solution for capturing C-level output streams (stdout/stderr) in Python applications through os.dup2 system calls. Wurlitzer provides flexible context managers for redirecting low-level output to Python streams, files, or logging objects, solving the common problem where standard Python stream redirection doesn't capture output from C extensions or system libraries.
5

6
## Package Information
7

8
- **Package Name**: wurlitzer
9
- **Version**: 3.1.1
10
- **Language**: Python
11
- **License**: MIT
12
- **Installation**: `pip install wurlitzer`
13
- **Repository**: https://github.com/minrk/wurlitzer
14

15
## Core Imports
16

17
```python
18
import wurlitzer
19
from wurlitzer import pipes, sys_pipes, PIPE, STDOUT
20
```
21

22
## Basic Usage
23

24
```python
25
from wurlitzer import pipes
26

27
# Capture C-level output in context manager
28
with pipes() as (out, err):
29
    call_some_c_function()
30

31
stdout_content = out.read()
32
stderr_content = err.read()
33
```
34

35
## Architecture
36

37
Wurlitzer operates at the file descriptor level using `os.dup2` to redirect C-level stdout/stderr streams. It employs background threads with selectors for non-blocking pipe handling, ensuring thread safety and GIL-aware operation. The library provides multiple output destinations including StringIO objects, file handles, Python loggers, and direct system stream forwarding.
38

39
Key architectural components:
40
- **File descriptor manipulation**: Uses `os.dup2` for low-level stream redirection
41
- **Thread-based forwarding**: Background threads handle pipe reading without blocking
42
- **Cross-platform compatibility**: Works on Linux, macOS with platform-specific optimizations
43
- **Buffer management**: Configurable pipe buffer sizes with automatic optimization
44

45
## Capabilities
46

47
### Context Manager Output Capture
48

49
Primary functionality for temporarily capturing C-level output in context managers.
50

51
```python { .api }
52
def pipes(stdout=PIPE, stderr=PIPE, encoding='utf-8', bufsize=None):
53
    """Capture C-level stdout/stderr in a context manager.
54
    
55
    Returns:
56
        Tuple of (stdout, stderr) streams
57
    """
58
```
59

60
[Output Capture](./output-capture.md)
61

62
### System Stream Forwarding
63

64
Forward C-level output to Python's sys.stdout/stderr, useful for Jupyter/IPython integration.
65

66
```python { .api }
67
def sys_pipes(encoding='utf-8', bufsize=None):
68
    """Redirect C-level stdout/stderr to sys.stdout/stderr"""
69
```
70

71
[System Integration](./system-integration.md)
72

73
### Permanent Output Redirection
74

75
Enable and disable permanent C-level output forwarding without context managers.
76

77
```python { .api }
78
def sys_pipes_forever(encoding='utf-8', bufsize=None):
79
    """Redirect all C output to sys.stdout/err permanently"""
80

81
def stop_sys_pipes():
82
    """Stop permanent redirection started by sys_pipes_forever"""
83
```
84

85
[Permanent Redirection](./permanent-redirection.md)
86

87
### IPython/Jupyter Extension
88

89
Magic command support for seamless integration with Jupyter notebooks and IPython.
90

91
```python { .api }
92
def load_ipython_extension(ip):
93
    """Register wurlitzer as an IPython extension"""
94

95
def unload_ipython_extension(ip):
96
    """Unload wurlitzer IPython extension"""
97
```
98

99
[IPython Integration](./ipython-integration.md)
100

101
### Core Implementation
102

103
Low-level Wurlitzer class providing the underlying capture mechanism.
104

105
```python { .api }
106
class Wurlitzer:
107
    """Class for Capturing Process-level FD output via dup2"""
108
    
109
    def __init__(self, stdout=None, stderr=None, encoding='utf-8', bufsize=None):
110
        """Initialize Wurlitzer with output destinations"""
111
```
112

113
[Core Implementation](./core-implementation.md)
114

115
## Constants and Configuration
116

117
```python { .api }
118
PIPE = 3  # Indicates pipe capture should be used
119
STDOUT = 2  # Redirect stderr to stdout destination
120
```
121

122
These constants control output routing behavior:
123
- `PIPE`: Creates new StringIO/BytesIO objects for output capture
124
- `STDOUT`: Redirects stderr to the same destination as stdout