Docker SDK for Python

repository·main·Indexed 27 days ago

A Python library providing a Pythonic interface to the Docker Engine API. It allows developers to manage containers, images, networks, volumes, and Swarms. The SDK offers a high-level DockerClient for common operations and a low-level APIClient for direct API access, supporting various connection protocols including Unix sockets, TCP, Windows Named Pipes, and SSH.

Tokens: 12.1K
Snippets: 21
Records: 133
Agent score: 92%

What's inside docker-py

Use DockerClient for high-level operations
main
Starting from version 2.0.0, the SDK provides docker.DockerClient as a high-level, user-focused API. While APIClient provides a low-level interface closer to the Docker Engine API, DockerClient is recommended for most standard use cases. docker.from_env() is the preferred way to instantiate a DockerClient.
https://github.com/docker/docker-py/blob/main/docs/change-log.md
Migrate from legacy docker-py to docker package
main
The name of the pip package has changed from docker-py to docker. To avoid naming conflicts, ensure you do not have both docker-py and docker installed simultaneously. New versions of the library are only published under the docker name.
https://github.com/docker/docker-py/blob/main/docs/change-log.md
Manage Docker Swarm mode using the Swarm API
main
The docker.models.swarm.Swarm class provides methods to manage Docker Engine's swarm mode. To use swarm methods, the Docker Engine must first be part of a swarm. You can achieve this by either initializing a new swarm or joining an existing one via the client.swarm attribute.
https://github.com/docker/docker-py/blob/main/docs/swarm.rst
Update Swarm service configuration
main
Use the APIClient.update_service method to modify a service. This method requires a version argument to prevent concurrent write conflicts; this version index must be retrieved first via APIClient.inspect_service from the ['Version']['Index'] key. You can update parameters like name and task_template.
```
container_spec = docker.types.ContainerSpec(
    image='busybox', command=['echo', 'hello world']
)
task_tmpl = docker.types.TaskTemplate(container_spec)

svc_version = client.inspect_service(svc_id)['Version']['Index']

client.update_service(
    svc_id, svc_version, name='new_name', task_template=task_tmpl
)
```
https://github.com/docker/docker-py/blob/main/docs/user_guides/swarm_services.md
Create a Docker client manually with DockerClient
main
For more granular control, you can manually instantiate the DockerClient class to configure your connection to the Docker daemon.
https://github.com/docker/docker-py/blob/main/docs/client.rst
Install docker with TLS support
main
As of version 6.0.0, the docker[tls] extra is deprecated and no longer necessary because TLS support is always available in the base docker package. You should simply use pip install docker.
```
pip install docker
```
https://github.com/docker/docker-py/blob/main/docs/change-log.md
List Swarm services
main
Use the APIClient.services method to list existing services. You can provide a filters dictionary to narrow down the results (e.g., by name).
```
client.services(filters={'name': 'mysql'})
```
https://github.com/docker/docker-py/blob/main/docs/user_guides/swarm_services.md
Handle Docker exceptions and errors
main
The client raises DockerExceptions and its subclasses when appropriate. To catch these errors, import them from the docker.errors module. Note that docker.APIError has also been moved to the docker.errors module.
```
from docker.errors import DockerException

try:
    # perform docker operation
    pass
except DockerException as e:
    print(f'An error occurred: {e}')
```
https://github.com/docker/docker-py/blob/main/docs/change-log.md
Remove a Swarm service
main
Use the APIClient.remove_service method to delete a service. You can identify the service using either its name or its ID.
```
client.remove_service('my_service_name')
```
https://github.com/docker/docker-py/blob/main/docs/user_guides/swarm_services.md
Upgrade to Docker SDK for Python v2.0.0+ (Breaking Changes)
main
If you are upgrading from a version prior to 2.0.0, note the following breaking changes:
- Client Renaming: docker.Client is now docker.APIClient.
- Client Type: docker.from_env() now returns a DockerClient instance instead of an APIClient.
- Python Support: Support for Python 2.6 has been dropped.
- Minimum API Version: The minimum supported API version is now 1.21 (Engine version 1.9.0+).
- Module Relocations:
  docker.ssladapter $\rightarrow$ docker.transport.ssladapter
  docker.utils.types $\rightarrow$ docker.types
- Utility Class Changes: create_host_config, create_ipam_pool, and create_ipam_config have been removed from docker.utils. Use the following classes in docker.types instead:
  HostConfig
  IPAMPool
  IPAMConfig
https://github.com/docker/docker-py/blob/main/docs/change-log.md
Install the Docker SDK for Python
main
Install the latest stable version of the Docker SDK for Python using pip.
Note: For versions older than 6.0, docker[tls] was required for SSL/TLS support. In current versions, this is no longer necessary but remains supported for backwards compatibility.
```
pip install docker
```
https://github.com/docker/docker-py/blob/main/README.md
Configure TLS for DockerClient and APIClient
main
Both docker.client.DockerClient and docker.api.client.APIClient support TLS connections. While docker.client.from_env() configures TLS automatically based on environment variables, you can manually configure TLS by passing a docker.tls.TLSConfig object to the tls parameter of the client constructor.
https://github.com/docker/docker-py/blob/main/docs/tls.rst