0
# dockerpty
1

2
Python library to use the pseudo-tty of a docker container. dockerpty provides functionality to operate the pseudo-tty (PTY) allocated to a Docker container using the Python client, enabling developers to interact with Docker containers through a terminal interface by establishing a bridge between the host system's TTY and the container's PTY.
3

4
## Package Information
5

6
- **Package Name**: dockerpty
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install dockerpty`
10
- **Dependencies**: `six >= 1.3.0` (docker-py assumed to be installed)
11

12
## Core Imports
13

14
```python
15
import dockerpty
16
```
17

18
For advanced usage with specific classes:
19

20
```python
21
from dockerpty import PseudoTerminal, RunOperation, ExecOperation
22
```
23

24
## Basic Usage
25

26
```python
27
import docker
28
import dockerpty
29

30
# Create Docker client and container
31
client = docker.Client()
32
container = client.create_container(
33
    image='busybox:latest',
34
    stdin_open=True,
35
    tty=True,
36
    command='/bin/sh',
37
)
38

39
# Start PTY session - this will hijack the current terminal
40
dockerpty.start(client, container)
41
```
42

43
Execute commands in existing containers:
44

45
```python
46
import docker
47
import dockerpty
48

49
client = docker.Client()
50
container = 'container_id_or_name'
51

52
# Execute a command with PTY support
53
dockerpty.exec_command(client, container, '/bin/bash')
54
```
55

56
## Architecture
57

58
dockerpty uses a multi-layered architecture for terminal management:
59

60
- **PseudoTerminal**: Core class that manages PTY allocation and terminal hijacking
61
- **Operations**: Abstract the differences between `docker run` (RunOperation) and `docker exec` (ExecOperation)
62
- **Stream Management**: Handles I/O multiplexing/demultiplexing and pumping data between streams
63
- **Terminal Control**: Manages raw mode configuration, signal handling, and resource cleanup
64

65
The library handles complexities including raw mode configuration, non-blocking I/O operations, signal handling for window resizing (SIGWINCH), and proper resource cleanup.
66

67
## Capabilities
68

69
### Main Entry Points
70

71
High-level functions that provide the primary interface to dockerpty's functionality. These are convenience wrappers around the core PseudoTerminal class.
72

73
```python { .api }
74
def start(client, container, interactive=True, stdout=None, stderr=None, stdin=None, logs=None):
75
    """Present the PTY of the container inside the current process."""
76

77
def exec_command(client, container, command, interactive=True, stdout=None, stderr=None, stdin=None):
78
    """Run provided command via exec API in provided container."""
79

80
def start_exec(client, exec_id, interactive=True, stdout=None, stderr=None, stdin=None):
81
    """Start an exec session using exec_id."""
82
```
83

84
[Main Entry Points](./main-entry-points.md)
85

86
### Core PTY Management
87

88
The core classes that handle pseudo-terminal allocation, management, and control. PseudoTerminal is the main class that coordinates terminal operations.
89

90
```python { .api }
91
class PseudoTerminal:
92
    def __init__(self, client, operation):
93
        """Initialize the PTY using the docker.Client instance and operation."""
94
    
95
    def start(self, sockets=None):
96
        """Start PTY management with terminal hijacking."""
97
    
98
    def resize(self, size=None):
99
        """Resize the container's PTY."""
100

101
class WINCHHandler:
102
    def __init__(self, pty):
103
        """Initialize a new WINCH handler for the given PTY."""
104
```
105

106
[Core PTY Management](./core-pty-management.md)
107

108
### Container Operations
109

110
Operation classes that abstract the differences between running containers and executing commands in existing containers.
111

112
```python { .api }
113
class RunOperation:
114
    def __init__(self, client, container, interactive=True, stdout=None, stderr=None, stdin=None, logs=None):
115
        """Initialize the PTY for docker run-like operations."""
116

117
class ExecOperation:
118
    def __init__(self, client, exec_id, interactive=True, stdout=None, stderr=None, stdin=None):
119
        """Initialize the PTY for docker exec-like operations."""
120

121
def exec_create(client, container, command, interactive=True):
122
    """Create exec instance for container."""
123
```
124

125
[Container Operations](./container-operations.md)
126

127
### Stream Management
128

129
Classes for handling I/O streams, multiplexing/demultiplexing, and data pumping between file descriptors.
130

131
```python { .api }
132
class Stream:
133
    def __init__(self, fd):
134
        """Initialize the Stream for the file descriptor."""
135

136
class Demuxer:
137
    def __init__(self, stream):
138
        """Initialize a new Demuxer reading from stream."""
139

140
class Pump:
141
    def __init__(self, from_stream, to_stream, wait_for_output=True, propagate_close=True):
142
        """Initialize a Pump with a Stream to read from and another to write to."""
143
```
144

145
[Stream Management](./stream-management.md)
146

147
### Terminal Control
148

149
Low-level terminal management for handling raw mode, TTY size detection, and terminal attribute manipulation.
150

151
```python { .api }
152
class Terminal:
153
    def __init__(self, fd, raw=True):
154
        """Initialize a terminal for the tty with stdin attached to fd."""
155

156
def size(fd):
157
    """Return a tuple (rows,cols) representing the size of the TTY fd."""
158

159
def set_blocking(fd, blocking=True):
160
    """Set the given file-descriptor blocking or non-blocking."""
161

162
def select(read_streams, write_streams, timeout=0):
163
    """Select the streams ready for reading, and streams ready for writing."""
164
```
165

166
[Terminal Control](./terminal-control.md)
167

168
## Types
169

170
```python { .api }
171
# Error constants
172
class Stream:
173
    ERRNO_RECOVERABLE = [errno.EINTR, errno.EDEADLK, errno.EWOULDBLOCK]
174
```