Utilities & Helpers

Motivation

The docker-py library relies on several supporting utilities and helpers to provide a comprehensive and robust interface for interacting with Docker. These components enhance core functionality, streamline interactions with the Docker daemon, and offer convenient abstractions. Familiarity with these utilities is crucial for leveraging the full capabilities of docker-py and achieving efficient interaction with the Docker ecosystem.

Subtopics

• docker.utils:

  • parse_host: docker/utils.py Parses a Docker host string, resolving it to a suitable format for establishing connections. This function handles various input formats, including standard URLs, Unix sockets, and custom schemes.

    from docker.utils import parse_host
              
              # Example usage:
              host = parse_host('tcp://localhost:2376')  # Standard TCP connection
              host = parse_host('unix:///var/run/docker.sock')  # Unix socket
              host = parse_host('http://192.168.99.100:8080') # HTTP connection
              

  • convert_port: docker/utils.py Converts port specifications from various formats (e.g., 80/tcp, 80/udp, 80) to a standardized format suitable for use with the Docker API.

    from docker.utils import convert_port
              
              # Example usage:
              port = convert_port('80/tcp')  # Converts to ('80', 'tcp')
              port = convert_port('80/udp')  # Converts to ('80', 'udp')
              port = convert_port('80')     # Converts to ('80', 'tcp') 
              

• docker.types:

  • Mount: docker/types.py Represents a Docker volume mount, encapsulating attributes like source, destination, mode, and other relevant settings. This class provides a standardized way to define and manage volume mounts when interacting with Docker.

    from docker.types import Mount
              
              # Example usage:
              mount = Mount(source='/data', target='/app/data', type='bind', read_only=True) 
              mount = Mount(source='some_volume', target='/app/data', type='volume') 
              

  • LogConfig: docker/types.py Defines configuration for container logs, allowing you to specify logging drivers, options, and preferences.

    from docker.types import LogConfig
              
              # Example usage:
              log_config = LogConfig(type='json-file', config={'max-size': '10m', 'max-file': '3'})
              

• docker.errors:

  • DockerException: docker/errors.py The base exception class for all Docker-related errors, providing a common hierarchy for handling different error scenarios.

    from docker.errors import DockerException
              
              try:
                  # Code that interacts with Docker
              except DockerException as e:
                  print(f"Docker Error: {e}")
              

  • APIError: docker/errors.py Represents errors related to interactions with the Docker API, often indicating issues with requests, responses, or communication with the Docker daemon.

    from docker.errors import APIError
              
              try:
                  # Code that interacts with Docker
              except APIError as e:
                  print(f"Docker API Error: {e}")
              

• docker.client:

  • APIClient: docker/client.py The primary interface for interacting with the Docker API. It provides methods for managing containers, images, networks, volumes, and other Docker resources.

    from docker import APIClient
              
              # Example usage:
              client = APIClient(base_url='unix:///var/run/docker.sock')
              # ... perform operations using the client
              client.close()
              

  • auto_adapt_scheme: docker/client.py This function helps automatically determine the appropriate scheme (e.g., http, https, unix) to be used for connecting to the Docker daemon, based on the specified base URL.

    from docker.client import auto_adapt_scheme
              
              # Example usage:
              scheme = auto_adapt_scheme('unix:///var/run/docker.sock')  # Scheme: 'unix'
              scheme = auto_adapt_scheme('tcp://localhost:2376')  # Scheme: 'http' 
              

• docker.auth:

  • BasicAuth: docker/auth.py Implements basic authentication for Docker registries, supporting username/password credentials.

    from docker.auth import BasicAuth
              
              # Example usage:
              auth = BasicAuth('username', 'password')
              

  • AuthConfig: docker/auth.py Represents authentication configuration for accessing Docker registries, including username, password, registry address, and other relevant details.

    from docker.auth import AuthConfig
              
              # Example usage:
              auth_config = AuthConfig(username='username', password='password', serveraddress='registry.example.com')