dockerpty: Pseudo-TTY handler for Docker Python client

Warnings

• breaking dockerpty (v0.4.1) is incompatible with Docker SDK for Python (package `docker`) versions 2.0 and above. It relies on the `client.inspect_container()` method, which was moved to `APIClient.inspect_container()` in `docker` SDK v2.0, causing `AttributeError`.
  Fix: Use the `docker-py` library (e.g., `pip install docker-py==1.10.6`) instead of the `docker` (Docker SDK for Python) library when using `dockerpty`. For new projects, consider using the native `attach()` or `exec_run()` methods provided by the modern Docker SDK for Python as alternatives to `dockerpty`.
• deprecated The `dockerpty` library has not been updated since February 2016 (version 0.4.1). It relies on the now-deprecated `docker-py` library. For modern Python applications, it's generally recommended to use the official Docker SDK for Python (`pip install docker`) and its built-in functionalities like `container.attach()` or `container.exec_run()` for interactive container sessions.
  Fix: For new development, explore the `attach()` and `exec_run()` methods of the official `docker` SDK for Python. If `dockerpty`'s specific features are required, be aware of its unmaintained status and dependency on older Docker client versions.
• gotcha For full interactive terminal control, the Docker container must be created with `stdin_open=True` and `tty=True`. If these flags are not set, `dockerpty` can still stream container output but will not provide interactive input or pseudo-terminal resizing.
  Fix: Always ensure `stdin_open=True` and `tty=True` are passed to `client.create_container()` when intending to use `dockerpty` for interactive PTY sessions.
• gotcha The key sequence `C-p C-q` (Ctrl+p then Ctrl+q) will detach from the container's pseudo-terminal, leaving the container running in the background. This is standard Docker behavior for detaching from an attached container.
  Fix: Be aware of this key sequence if you intend to gracefully detach from an interactive container without stopping it. To stop the container, typically type 'exit' into the container's shell.
• deprecated An internal `DeprecationWarning` exists within `dockerpty/pty.py` (v0.4.1) indicating that a future version will require the `logs=1` argument in `dockerpty.start()` to maintain current behavior. While `dockerpty` has not seen new releases, it's a good practice to include `logs=1` when calling `dockerpty.start()` to avoid potential issues or warnings from the library itself.
  Fix: Pass `logs=1` as a keyword argument to `dockerpty.start()`: `dockerpty.start(client, container, logs=1)`.

Install

• pip install dockerpty Install dockerpty

Imports

• dockerpty

  import dockerpty

  Primary import for using the library's `start()` function.
• PseudoTerminal

  from dockerpty import PseudoTerminal

  Used for more explicit object-oriented control over the PTY, as shown in some examples.

Quickstart

This example demonstrates how to create and attach to an interactive shell within a Docker container using `dockerpty`. It uses the `docker.Client()` class from the older `docker-py` library to interact with the Docker daemon. The container is created with `stdin_open=True` and `tty=True` to enable interactive terminal functionality. The `dockerpty.start()` function then takes control of the current terminal, piping its input/output to/from the container's PTY.

import docker
import dockerpty
import os

# Ensure docker-py is installed: pip install docker-py
# This example uses the older docker-py client API.
# For modern Docker SDK for Python, direct use of `attach()` or `exec_run()` might be preferred.

# For demonstration, ensure a Docker daemon is running.
# For this example to be interactive, run it in a terminal.

try:
    # Using the older docker.Client() from docker-py
    # Modern Docker SDK uses docker.from_env() or docker.DockerClient()
    # For this example to work with docker-py, install it:
    # pip install docker-py
    client = docker.Client(base_url=os.environ.get('DOCKER_HOST', 'unix://var/run/docker.sock'))

    # Create a container with TTY and stdin_open for interactive use
    container = client.create_container(
        image='busybox:latest',
        stdin_open=True,
        tty=True,
        command='/bin/sh',
    )
    print(f"Container created with ID: {container['Id']}")

    # Start the container
    client.start(container)

    print("Attaching to container's PTY. Type 'exit' to quit the shell and container.")
    # Attach to the container's pseudo-terminal
    # Passing logs=1 is recommended due to an internal DeprecationWarning in dockerpty 0.4.1
    dockerpty.start(client, container, logs=1)

    print(f"Container {container['Id']} exited.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure Docker daemon is running and `docker-py` is installed (not just `docker` SDK). ")
    print("This library is designed for an older Docker client version.")
finally:
    # Clean up the container
    if 'container' in locals() and client:
        try:
            client.remove_container(container, v=True, force=True)
            print(f"Container {container['Id']} removed.")
        except Exception as e:
            print(f"Error removing container: {e}")