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
```