0
# Main Entry Points
1

2
High-level functions that provide the primary interface to dockerpty's functionality. These convenience functions wrap the core PseudoTerminal class and handle the most common use cases for Docker container PTY management.
3

4
## Capabilities
5

6
### Container PTY Startup
7

8
Start a PTY session with a Docker container, taking over the current process' TTY until the container's PTY is closed.
9

10
```python { .api }
11
def start(client, container, interactive=True, stdout=None, stderr=None, stdin=None, logs=None):
12
    """
13
    Present the PTY of the container inside the current process.
14
    
15
    This is a wrapper for PseudoTerminal(client, RunOperation(...)).start()
16
    
17
    Parameters:
18
    - client: Docker client instance
19
    - container: Container dict or ID
20
    - interactive: bool, whether to enable interactive mode (default: True)
21
    - stdout: file-like object for stdout (default: sys.stdout)
22
    - stderr: file-like object for stderr (default: sys.stderr)
23
    - stdin: file-like object for stdin (default: sys.stdin)
24
    - logs: int, whether to include logs (default: None, shows deprecation warning)
25
    
26
    Returns:
27
    None - function takes over terminal until container exits
28
    """
29
```
30

31
Usage example:
32

33
```python
34
import docker
35
import dockerpty
36

37
client = docker.Client()
38
container = client.create_container(
39
    image='ubuntu:latest',
40
    stdin_open=True,
41
    tty=True,
42
    command='/bin/bash',
43
)
44

45
# This will hijack the current terminal
46
dockerpty.start(client, container)
47
```
48

49
### Exec Command Execution
50

51
Execute a command in an existing container with PTY support.
52

53
```python { .api }
54
def exec_command(client, container, command, interactive=True, stdout=None, stderr=None, stdin=None):
55
    """
56
    Run provided command via exec API in provided container.
57
    
58
    This is a wrapper for PseudoTerminal(client, ExecOperation(...)).start()
59
    
60
    Parameters:
61
    - client: Docker client instance
62
    - container: Container dict or ID
63
    - command: str or list, command to execute
64
    - interactive: bool, whether to enable interactive mode (default: True)
65
    - stdout: file-like object for stdout (default: sys.stdout)
66
    - stderr: file-like object for stderr (default: sys.stderr)
67
    - stdin: file-like object for stdin (default: sys.stdin)
68
    
69
    Returns:
70
    None - function takes over terminal until command completes
71
    """
72
```
73

74
Usage example:
75

76
```python
77
import docker
78
import dockerpty
79

80
client = docker.Client()
81
container_id = 'running_container_id'
82

83
# Execute bash in the running container
84
dockerpty.exec_command(client, container_id, '/bin/bash')
85
```
86

87
### Exec Session Startup
88

89
Start a previously created exec instance with PTY support.
90

91
```python { .api }
92
def start_exec(client, exec_id, interactive=True, stdout=None, stderr=None, stdin=None):
93
    """
94
    Start an exec session using exec_id.
95
    
96
    Parameters:
97
    - client: Docker client instance
98
    - exec_id: Exec instance ID (from client.exec_create())
99
    - interactive: bool, whether to enable interactive mode (default: True)
100
    - stdout: file-like object for stdout (default: sys.stdout)
101
    - stderr: file-like object for stderr (default: sys.stderr)
102
    - stdin: file-like object for stdin (default: sys.stdin)
103
    
104
    Returns:
105
    None - function takes over terminal until exec completes
106
    """
107
```
108

109
Usage example:
110

111
```python
112
import docker
113
import dockerpty
114

115
client = docker.Client()
116
container_id = 'running_container_id'
117

118
# Create exec instance
119
exec_id = client.exec_create(container_id, '/bin/sh', tty=True, stdin=True)
120

121
# Start the exec session with PTY
122
dockerpty.start_exec(client, exec_id['Id'])
123
```
124

125
## Important Notes
126

127
- All these functions will **hijack the current terminal** until the container or command exits
128
- When dockerpty starts, control is yielded to the container's PTY
129
- Press `C-p C-q` to detach from the container while keeping it running
130
- These are safe operations - all resources are restored to their original states on exit
131
- For non-TTY containers, dockerpty can still stream output but cannot provide interactive control