Python on Whales

https://gabrieldemarmiesse.github.io/python-on-whales
Admin
Python on Whales is a Docker client library for Python that provides a fun and intuitive interface...
Tokens:66,424
Snippets:460
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### start

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/pod

Starts one or more pods.

```APIDOC
## start

### Description
Starts one or more pods.

### Parameters
- **x** (Union[ValidPod, Iterable[ValidPod]]) - Required - One or more pods to start

### Raises
- **python_on_whales.exceptions.NoSuchPod** - If any pods do not exist.
```

--------------------------------

### up()

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/compose

Starts the containers for the Docker Compose project.

```APIDOC
## up()

### Description
Start the containers. Reading the logs of the containers is not yet implemented.

### Parameters
- **services** (Union[List[str], str, None]) - Optional - The services to start. If None (default), all services are started.
- **build** (bool) - Optional - If True, build the docker images before starting the containers.
- **detach** (bool) - Optional - If True, run the containers in the background.
- **abort_on_container_exit** (bool) - Optional - If True stops all containers if any container was stopped.
- **scales** (Dict[str, int]) - Optional - Scale SERVICE to NUM instances.
- **attach_dependencies** (bool) - Optional - Attach to dependent containers.
- **force_recreate** (bool) - Optional - Recreate containers even if their configuration and image haven't changed.
- **recreate** (bool) - Optional - Recreate the containers if already exist.
- **no_build** (bool) - Optional - Don't build an image, even if it's missing.
- **remove_orphans** (bool) - Optional - Remove containers for services not defined in the Compose file.
- **renew_anon_volumes** (bool) - Optional - Recreate anonymous volumes instead of retrieving data from the previous containers.
- **color** (bool) - Optional - If False, it will produce monochrome output.
- **log_prefix** (bool) - Optional - If False, will not display the prefix in the logs.
- **start** (bool) - Optional - Start the service after creating them.
- **quiet** (bool) - Optional - Set quiet=True to avoid having any output.
- **wait** (bool) - Optional - Wait for services to be running/healthy.
- **no_attach_services** (Union[List[str], str, None]) - Optional - The services not to attach to.
- **pull** (Literal['always', 'missing', 'never', None]) - Optional - Pull image before running.
- **stream_logs** (bool) - Optional - If True, returns an Iterable of logs.
- **wait_timeout** (Optional[int]) - Optional - Maximum duration to wait for the project to be running/healthy.
- **dependencies** (bool) - Optional - Also start linked services.
```

--------------------------------

### PluginCLI - Install Plugin

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/plugin

Installs a Docker plugin from a registry.

```APIDOC
## POST /plugins/install

### Description
Installs a Docker plugin.

### Method
POST

### Endpoint
/plugins/install

### Parameters
#### Query Parameters
- **plugin_name** (str) - Required - The name of the plugin you want to install.
- **configuration** (Dict[str, str]) - Optional - A dict adding configuration options to the plugin. Defaults to {}.
- **alias** (Optional[str]) - Optional - Local name for plugin. Defaults to None.
- **disable** (bool) - Optional - Do not enable the plugin on install. Defaults to False.
- **disable_content_trust** (bool) - Optional - Skip image verification. Defaults to True.

### Request Example
```json
{
  "plugin_name": "my-plugin",
  "configuration": {"key": "value"},
  "alias": "my-alias",
  "disable": false,
  "disable_content_trust": false
}
```

### Response
#### Success Response (200)
- **plugin_object** (python_on_whales.Plugin) - The installed plugin object.

#### Response Example
```json
{
  "id": "plugin-id",
  "name": "my-plugin"
}
```
```

--------------------------------

### Install, Inspect, and List Docker Plugins

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/plugins

Use these methods to manage Docker plugins. Avoid using the constructor directly. Ensure you have the 'python-on-whales' library installed.

```python
from python_on_whales import docker

my_docker_plugin = docker.plugin.install("vieux/sshfs:latest")
# or
my_docker_plugin = docker.plugin.inspect("vieux/sshfs:latest")
# or
list_of_plugins = docker.plugins.list()
```

--------------------------------

### POST /pod create

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/pod

Creates a pod but does not start it. The pod can be started later using the `.start()` method.

```APIDOC
## POST /pod create

### Description
Creates a pod, but does not start it. Start it then with the `.start()` method.

### Method
POST

### Endpoint
/pod

### Parameters
#### Query Parameters
- **name** (Optional[str]) - Optional - The name to set the pod to. If not specified a name is generated.
- **add_hosts** (Iterable[Tuple[str, str]]) - Optional - Add a custom host-to-IP mapping (format 'host:ip'), which adds a line to /etc/hosts. Conflicts with the no_hosts option.
- **cgroup_parent** (Optional[str]) - Optional - Path to cgroups under which the cgroup for the pod is created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process.
- **cpus** (Optional[float]) - Optional - Set the total number of CPUs delegated to the pod. The default is 0.0 indicating that there is no limit on computation power.
- **cpuset_cpus** (Optional[Iterable[int]]) - Optional - CPUs in which to allow execution.
- **devices** (Iterable[str]) - Optional - List of device names to pass from the host to containers in the pod.
- **device_read_bps** (Iterable[str]) - Optional - Limit read rate (in bytes per second) from a device (e.g. device_read_bps=/dev/sda:1mb).
- **dns** (Iterable[str]) - Optional - Set custom DNS servers in the /etc/resolv.conf file that is shared between all containers in the pod.
- **dns_options** (Iterable[str]) - Optional - Set custom DNS options in the /etc/resolv.conf file that is shared between all containers in the pod.
- **dns_search** (Iterable[str]) - Optional - Set custom DNS search domains in the /etc/resolv.conf file that is shared between all containers in the pod.
- **exit_policy** (Optional[str]) - Optional - Set the exit policy of the pod when the last container exits. Supported policies are 'continue' (default) and 'stop'.
- **gidmaps** (Iterable[Tuple[int, int, int]]) - Optional - GID map for the user namespace. Using this flag runs all containers in the pod with user namespace enabled. It conflicts with the --userns and --subgidname flags.
- **hostname** (Optional[str]) - Optional - Set the pod's hostname.
- **infra** (Optional[bool]) - Optional - Whether to create an infra container and associate it with the pod. An infra container is a lightweight container used to coordinate the shared kernel namespace of a pod.
- **infra_command** (Optional[str]) - Optional - Specify the command that is run to start the infra container.
- **infra_conmon_pidfile** (Optional[ValidPath]) - Optional - Write the pid of the infra container's conmon process to a file.
- **infra_image** (Optional[ValidImage]) - Optional - The custom image that is used for the infra container.
- **infra_name** (Optional[str]) - Optional - The name that is used for the pod's infra container.
- **ip** (Optional[str]) - Optional - Specify a static IPv4 address for the pod, for example 10.88.64.128. This option can only be used if the pod is joined to only a single network - i.e., network=network-name is used at most once - and if the pod is not joining another container's network namespace via network=container:id. The address must be within the network's IP address pool (default 10.88.0.0/16).
- **ip6** (Optional[str]) - Optional - Specify a static IPv6 address for the pod, for example fd46:db93:aa76:ac37::10. This option can only be used if the pod is joined to only a single network (see note on the ip argument). The address must be within the network's IPv6 address pool.
- **labels** (Mapping[str, str]) - Optional - Add metadata labels to a pod.
- **label_files** (Iterable[ValidPath]) - Optional - Read in a line-delimited file of labels.
- **mac_address** (Optional[str]) - Optional - Pod network interface MAC address (e.g. 92:d0:c6:0a:29:33). This option can only be used if the pod is joined to only a single network (see note on the ip argument).
- **memory** (Union[int, str, None]) - Optional - Memory limit for the pod.

### Request Example
```json
{
  "name": "my-pod",
  "labels": {"environment": "production"},
  "memory": "512mb"
}
```

### Response
#### Success Response (200)
- **pod_id** (str) - The ID of the created pod.

#### Response Example
```json
{
  "pod_id": "a1b2c3d4e5f6"
}
```
```

--------------------------------

### Start Services

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/compose

Starts one or more specified Docker Compose services. If no services are specified, all services are started.

```APIDOC
## POST /start

### Description
Start the specified services.

### Method
POST

### Endpoint
/start

### Parameters
#### Request Body
- **services** (Union[str, List[str], None]) - Optional - The names of one or more services to start. If `None`, all services start. If an empty list, it's a no-op. Defaults to `None`.
- **stream_logs** (bool) - Optional - If `False`, returns `None`. If `True`, returns an Iterable of `Tuple[str, bytes]` for logs. Defaults to `False`.

### Response
#### Success Response (200)
- **result** (Optional[Iterable[Tuple[str, bytes]]]) - Logs if `stream_logs` is `True`, otherwise `None`.

### Request Example
```json
{
  "services": ["web", "db"]
}
```

### Response Example
```json
{
  "result": null
}
```
```

--------------------------------

### Bake Usage Example

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/buildx

Examples of using the bake function to run builds and to retrieve configuration without running builds.

```python
from python_on_whales import docker

# returns the config used and runs the builds
config = docker.buildx.bake(["my_target1", "my_target2"], load=True)
assert config == {
    "target": {
        "my_target1": {
            "context": "./",
            "dockerfile": "Dockerfile",
            "tags": ["pretty_image1:1.0.0"],
            "target": "out1",
            "output": ["type=docker"]
        },
        "my_target2": {
            "context": "./",
            "dockerfile": "Dockerfile",
            "tags": ["pretty_image2:1.0.0"],
            "target": "out2",
            "output": ["type=docker"]
        }
    }
}

# returns the config only, doesn't run the builds
config = docker.buildx.bake(["my_target1", "my_target2"], load=True, print=True)
```

--------------------------------

### Start Containers

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/container

Starts one or more created or stopped containers. Can attach to stdio, run interactively, stream output, or override detach keys.

```python
start(containers, attach=False, interactive=False, stream=False, detach_keys=None)
```

--------------------------------

### Install python-on-whales via pip

Source: https://gabrieldemarmiesse.github.io/python-on-whales

Use this command to install the library in your Python environment.

```bash
pip install python-on-whales
```

--------------------------------

### Initialize Docker Swarm

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/swarm

Initializes a Docker Swarm. Use `docker.swarm.join_token` to get tokens for other nodes to join. This example shows initializing a swarm and joining a worker node via SSH.

```python
from python_on_whales import docker, DockerClient

worker_docker = DockerClient(host="ssh://worker_linux_user@worker_hostname")
# Here the docker variable is connected to the local daemon
# worker_docker is a connected to the Docker daemon of the
# worker through ssh, useful to control it without login to the machine
# manually.
docker.swarm.init()
my_token = docker.swarm.join_token("worker")  # you can set manager too
worker_docker.swarm.join("manager_hostname:2377", token=my_token)
```

--------------------------------

### Initialize Swarm and Create Service

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/services

This example demonstrates initializing a Docker swarm and then creating a service. It also shows how to define a helper function `super_print` to display the type and value of various service attributes.

```python
from python_on_whales import docker

docker.swarm.init()
my_service = docker.service.create("busybox", ["ping", "www.google.com"])

def super_print(obj):
    print(f"type = {type(obj)}, value = {obj}")

super_print(my_service.id)
super_print(my_service.version)
super_print(my_service.created_at)
super_print(my_service.updated_at)
super_print(my_service.spec.name)
super_print(my_service.spec.labels)
super_print(my_service.spec.mode)
super_print(my_service.spec.update_config)
super_print(my_service.spec.rollback_config)
super_print(my_service.spec.task_template.container_spec.image)
super_print(my_service.spec.task_template.container_spec.labels)
super_print(my_service.spec.task_template.container_spec.privileges)
super_print(my_service.spec.task_template.container_spec.stop_grace_period)
super_print(my_service.spec.task_template.container_spec.isolation)
super_print(my_service.spec.task_template.container_spec.env)
super_print(my_service.spec.task_template.resources.limits)
super_print(my_service.spec.task_template.resources.reservations)
super_print(my_service.previous_spec)
super_print(my_service.endpoint.spec)
super_print(my_service.endpoint.ports)
super_print(my_service.endpoint.virtual_ips)
super_print(my_service.update_status)
```

--------------------------------

### Pulling and Inspecting Ubuntu Image Attributes

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/images

This example demonstrates pulling the 'ubuntu' image and then inspecting its various attributes like ID, repository tags, creation date, and configuration details.

```python
from python_on_whales import docker

image = docker.pull("ubuntu")

def super_print(obj):
    print(f"type={type(obj)}, value={obj}")

super_print(image.id)
super_print(image.repo_tags)
super_print(image.repo_digests)
super_print(image.parent)
super_print(image.comment)
super_print(image.created)
super_print(image.container)
super_print(image.container_config)
super_print(image.docker_version)
super_print(image.author)
super_print(image.config)
super_print(image.architecture)
super_print(image.os)
super_print(image.os_version)
super_print(image.size)
super_print(image.virtual_size)
super_print(image.graph_driver.name)
super_print(image.graph_driver.data)
super_print(image.root_fs.type)
super_print(image.root_fs.layers)
super_print(image.root_fs.base_layer)
super_print(image.metadata)
```

--------------------------------

### Container Start API

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/container

Starts one or more created or stopped containers. It supports attaching to the container's output and running in interactive mode.

```APIDOC
## POST /containers/start

### Description
Starts one or more created/stopped containers.

### Method
POST

### Endpoint
/containers/start

### Parameters
#### Query Parameters
- **containers** (Union[ValidContainer, Iterable[ValidContainer]]) - Required - One or a list of containers.
- **attach** (bool) - Optional - Attach stdout/stderr and forward signals. Default: False
- **interactive** (bool) - Optional - Attach stdin (ensure it is open). Default: False
- **stream** (bool) - Optional - Stream output as a generator. Default: False
- **detach_keys** (Optional[str]) - Optional - Override the key sequence for detaching a container. Default: None

### Response
#### Success Response (200)
- **output** (str or python_on_whales.Container) - The container output as a string if detach is `False` (the default), and a `python_on_whales.Container` if detach is `True`.

### Request Example
```json
{
  "containers": [
    "container_id_or_name_1",
    "container_id_or_name_2"
  ],
  "attach": true,
  "interactive": false,
  "stream": false,
  "detach_keys": null
}
```

### Response Example
```json
{
  "output": "Container started successfully."
}
```
```

--------------------------------

### Check if Buildx is Installed

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/buildx

Verifies if Docker Buildx is installed and operational on the system. If not installed, it suggests following installation instructions.

```python
from python_on_whales import docker

if docker.buildx.is_installed():
    print("Buildx is installed and working.")
else:
    print("Buildx is not installed. Please follow the installation guide.")
```

--------------------------------

### Create and Inspect Docker Service

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/services

Use `docker.service.create` to start a new service and `docker.service.inspect` to retrieve its details. Ensure `python-on-whales` is imported.

```python
from python_on_whales import docker

my_docker_service = docker.service.inspect("my-service")

my_docker_service = docker.service.create("busybox", ["ping", "www.google.com"])
```

--------------------------------

### Container Start API

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/containers

Start a stopped container. Options include attaching to streams and running in interactive mode.

```APIDOC
## Container Start API

### Description
Starts this container.

### Method
`start`

### Parameters
- **attach** (bool, optional) - Whether to attach to the container's streams. Defaults to False.
- **interactive** (bool, optional) - Whether to run in interactive mode. Defaults to False.
- **stream** (bool, optional) - Whether to stream the output. Defaults to False.
- **detach_keys** (str, optional) - Keys to detach from the stream.

### Request Example
```python
container.start(attach=True, interactive=True)
```

### Response
(No specific response details provided in the source text.)
```

--------------------------------

### Create a Container

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/container

Initializes a container without starting it, allowing for pre-start configuration like copying files.

```python
create(image, command=(), *, add_hosts=(), blkio_weight=None, blkio_weight_device=(), cap_add=(), cap_drop=(), cgroup_parent=None, cgroupns=None, cidfile=None, cpu_period=None, cpu_quota=None, cpu_rt_period=None, cpu_rt_runtime=None, cpu_shares=None, cpus=None, cpuset_cpus=None, cpuset_mems=None, detach=False, devices=(), device_cgroup_rules=(), device_read_bps=(), device_read_iops=(), device_write_bps=(), device_write_iops=(), content_trust=False, dns=(), dns_options=(), dns_search=(), domainname=None, entrypoint=None, envs={}, env_files=(), env_host=False, expose=(), gpus=None, groups_add=(), healthcheck=True, health_cmd=None, health_interval=None, health_retries=None, health_start_period=None, health_timeout=None, hostname=None, init=False, interactive=False, ip=None, ip6=None, ipc=None, isolation=None, kernel_memory=None, labels={}, label_files=(), link=(), link_local_ip=(), log_driver=None, log_options=(), mac_address=None, memory=None, memory_reservation=None, memory_swap=None, memory_swappiness=None, mounts=(), name=None, networks=(), network_aliases=(), oom_kill=True, oom_score_adj=None, pid=None, pids_limit=None, platform=None, pod=None, privileged=False, publish=(), publish_all=False, pull='missing', read_only=False, restart=None, remove=False, runtime=None, security_options=(), shm_size=None, sig_proxy=True, stop_signal=None, stop_timeout=None, storage_options=(), sysctl={}, systemd=None, tmpfs=(), tty=False, tz=None, ulimit=(), user=None, userns=None, uts=None, volumes=(), volume_driver=(), volumes_from=(), workdir=None)
```

--------------------------------

### top

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/pod

Get the running processes of a pod.

```APIDOC
## top

### Description
Get the running processes of a pod. Not yet implemented.
```

--------------------------------

### GET /buildx/inspect

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/buildx

Returns a builder instance from the name.

```APIDOC
## GET /buildx/inspect

### Description
Returns a builder instance from the name.

### Parameters
#### Query Parameters
- **x** (Optional[str]) - Optional - If None, returns the current builder. If a string is provided, the builder that has this name is returned.
- **bootstrap** (bool) - Optional - If set to True, ensure builder has booted before inspecting.

### Response
#### Success Response (200)
- **builder** (python_on_whales.Builder) - A python_on_whales.Builder object.
```

--------------------------------

### Inspect Container Network Settings

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/containers

Examples of accessing network configuration properties of a container object.

```python
In [141]: super_print(container.network_settings.secondary_ip_addresses)
type = <class 'NoneType'>, value = None
```

```python
In [142]: super_print(container.network_settings.secondary_ipv6_addresses)
type = <class 'NoneType'>, value = None
```

```python
In [143]: super_print(container.network_settings.endpoint_id)
type = <class 'str'>, value = c5b2f3029c50436eb4d455623d65e3f24fc4ec230315884e80b32d1fe40417cf
```

```python
In [144]: super_print(container.network_settings.gateway)
type = <class 'str'>, value = 172.17.0.1
```

```python
In [145]: super_print(container.network_settings.global_ipv6_address)
type = <class 'str'>, value = 
```

```python
In [146]: super_print(container.network_settings.global_ipv6_prefix_length)
type = <class 'int'>, value = 0
```

```python
In [147]: super_print(container.network_settings.ip_address)
type = <class 'str'>, value = 172.17.0.2
```

```python
In [148]: super_print(container.network_settings.ip_prefix_length)
type = <class 'int'>, value = 16
```

```python
In [149]: super_print(container.network_settings.ipv6_gateway)
type = <class 'str'>, value = 
```

```python
In [150]: super_print(container.network_settings.mac_address)
type = <class 'str'>, value = 0a:b1:01:d4:11:3a
```

```python
In [151]: super_print(container.network_settings.networks)
type = <class 'dict'>, value = {'bridge': NetworkInspectResult(ipam_config=None, links=None, aliases=None, network_id='eabe061a260dd729b83ab1a2b80e38743550db5dc6ebef1dce5b1e3719c9ffc6', endpoint_id='c5b2f3029c50436eb4d455623d65e3f24fc4ec230315884e80b32d1fe40417cf', gateway='172.17.0.1', ip_address='172.17.0.2', ip_prefix_length=16, ipv6_gateway='', global_ipv6_address='', global_ipv6_prefix_length=0, mac_address='0a:b1:01:d4:11:3a', driver_options=None)}
```

--------------------------------

### GET /config/list

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/config

Lists all available Docker configs in the swarm.

```APIDOC
## GET /config/list

### Description
List all config available in the swarm.

### Method
GET

### Endpoint
/config/list

### Parameters
#### Query Parameters
- **filters** (Dict[str, str]) - Optional - If you want to filter the results based on a given condition. For example, `docker.config.list(filters=dict(label="my_label=hello"))`. DEFAULT: {}

### Response
#### Success Response (200)
- **configs** (List[python_on_whales.Config]) - A `List[python_on_whales.Config]`.

#### Response Example
```json
{
  "configs": [
    {
      "id": "config_id_1",
      "version": 1,
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-01-01T12:00:00Z",
      "spec": {
        "name": "my_config_1",
        "labels": {},
        "file": {
          "name": "my_file_1.txt",
          "content": "file content 1",
          " உommand": null
        }
      }
    },
    {
      "id": "config_id_2",
      "version": 1,
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-01-01T12:00:00Z",
      "spec": {
        "name": "my_config_2",
        "labels": {},
        "file": {
          "name": "my_file_2.txt",
          "content": "file content 2",
          " உommand": null
        }
      }
    }
  ]
}
```
```

--------------------------------

### Inspecting Node Attributes

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/nodes

Interactive example demonstrating how to access various attributes of a node object.

```python
In [1]: from python_on_whales import docker

In [2]: docker.swarm.init()

In [3]: docker.node.list()[0]

In [4]: def super_print(obj):
   ...:     print(f"type = {type(obj)}, value = {obj}")
   ...:

In [4]: super_print(node.id)
type = <class 'str'>, value = wr8hl3wh2pwrjqnicep7gukyq

In [5]: super_print(node.version.index)
type = <class 'int'>, value = 9

In [6]: super_print(node.created_at)
type = <class 'datetime.datetime'>, value = 2026-03-09 14:18:02.713178+00:00

In [7]: super_print(node.updated_at)
type = <class 'datetime.datetime'>, value = 2026-03-09 14:18:03.316967+00:00

In [8]: super_print(node.spec.name)
type = <class 'NoneType'>, value = None

In [9]: super_print(node.spec.labels)
type = <class 'dict'>, value = {}

In [10]: super_print(node.spec.role)
type = <class 'str'>, value = manager

In [11]: super_print(node.spec.availability)
type = <class 'str'>, value = active

In [12]: super_print(node.description.hostname)
type = <class 'str'>, value = runnervm0kj6c

In [13]: super_print(node.description.platform.architecture)
type = <class 'str'>, value = x86_64

In [14]: super_print(node.description.platform.os)
type = <class 'str'>, value = linux

In [15]: super_print(node.description.resources.nano_cpus)
type = <class 'int'>, value = 4000000000

In [16]: super_print(node.description.resources.memory_bytes)
type = <class 'int'>, value = 16771559424

In [17]: super_print(node.description.resources.generic_resources)
type = <class 'NoneType'>, value = None

In [18]: super_print(node.description.engine.engine_version)
type = <class 'str'>, value = 28.0.4

In [19]: super_print(node.description.engine.labels)
type = <class 'NoneType'>, value = None

In [20]: super_print(node.description.engine.plugins)
type = <class 'list'>, value = [EnginePlugin(type='Log', name='awslogs'), EnginePlugin(type='Log', name='fluentd'), EnginePlugin(type='Log', name='gcplogs'), EnginePlugin(type='Log', name='gelf'), EnginePlugin(type='Log', name='journald'), EnginePlugin(type='Log', name='json-file'), EnginePlugin(type='Log', name='local'), EnginePlugin(type='Log', name='splunk'), EnginePlugin(type='Log', name='syslog'), EnginePlugin(type='Network', name='bridge'), EnginePlugin(type='Network', name='host'), EnginePlugin(type='Network', name='ipvlan'), EnginePlugin(type='Network', name='macvlan'), EnginePlugin(type='Network', name='null'), EnginePlugin(type='Network', name='overlay'), EnginePlugin(type='Volume', name='local'), EnginePlugin(type='Volume', name='mochoa/s3fs-volume-plugin:latest')]

In [21]: super_print(node.description.tls_info.trust_root)
type = <class 'str'>, value = -----BEGIN CERTIFICATE-----
MIIBazCCARCgAwIBAgIUCNuRt3tPuvJNknl2zIBitgcOZwMwCgYIKoZIzj0EAwIw
EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMjYwMzA5MTQxMzAwWhcNNDYwMzA0MTQx
MzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
A0IABBcYCj0ionwRE3r12+SSoMPjqMWPX8RI4UlbLzZlQmpsrxc8hJLcV+z8Y0u2
r8P+U2pn8JONHqb7fsQX9CsStD6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
Af8EBTADAQH/MB0GA1UdDgQWBBRGd1V8Y4rG+HHFs3eElX0ONJFGbTAKBggqhkjO
PQQDAgNJADBGAiEAu2I2cMMfn6nqnjLTTIyYL9rJ72QR+Nl5qTI0NOHmlNcCIQC8
ryrkcNUjyR1Tr057NL7tWoL0K9cqCcucRPOSLpC9tw==
-----END CERTIFICATE-----


In [22]: super_print(node.description.tls_info.cert_issuer_subject)
type = <class 'str'>, value = MBMxETAPBgNVBAMTCHN3YXJtLWNh

In [23]: super_print(node.description.tls_info.cert_issuer_public_key)
type = <class 'str'>, value = MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFxgKPSKifBETevXb5JKgw+OoxY9fxEjhSVsvNmVCamyvFzyEktxX7PxjS7avw/5Tamfwk40epvt+xBf0KxK0Pg==

In [24]: super_print(node.status.state)
type = <class 'str'>, value = ready

In [25]: super_print(node.status.message)
type = <class 'NoneType'>, value = None

In [26]: super_print(node.status.addr)
type = <class 'str'>, value = 10.1.1.193

In [27]: super_print(node.manager_status.leader)
type = <class 'bool'>, value = True

In [28]: super_print(node.manager_status.reachability)
type = <class 'str'>, value = reachable

In [29]: super_print(node.manager_status.addr)
type = <class 'str'>, value = 10.1.1.193:2377
```

--------------------------------

### GET /service/list

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/service

Returns the list of services.

```APIDOC
## GET /service/list

### Description
Returns the list of services.

### Parameters
#### Query Parameters
- **filters** (Union[Iterable[ServiceListFilter], Mapping[str, Any]]) - Optional - If you want to filter the results based on a given condition.
```

--------------------------------

### Plugin Management API

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/plugins

Provides methods for installing, inspecting, and listing Docker plugins.

```APIDOC
## Plugin Management

### Install Plugin

Installs a Docker plugin.

### Method

`docker.plugin.install(remote: str)`

### Endpoint

N/A (This is a library function)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example
```python
from python_on_whales import docker

my_docker_plugin = docker.plugin.install("vieux/sshfs:latest")
```

### Response

#### Success Response (200)

Returns a `Plugin` object representing the installed plugin.

#### Response Example
```json
{
  "id": "7623cab41f3c65434b33fd90abbf8de9a723f2528473527507d3d4effaffd581",
  "name": "mochoa/s3fs-volume-plugin:latest",
  "enabled": true,
  "settings": {
    "mounts": [],
    "env": [
      "AWSACCESSKEYID=",
      "AWSSECRETACCESSKEY=",
      "DEFAULT_S3FSOPTS=nomultipart,use_path_request_style"
    ],
    "args": [],
    "devices": [
      {
        "name": null,
        "path": null,
        "description": null
      }
    ]
  },
  "plugin_reference": "docker.io/mochoa/s3fs-volume-plugin:latest",
  "config": {
    "docker_version": "19.03.15",
    "description": "S3FS plugin for Docker v2.0.9",
    "documentation": "https://github.com/marcelo-ochoa/docker-volume-plugins/",
    "entrypoint": [
      "/usr/bin/tini",
      "--",
      "/s3fs-volume-plugin"
    ],
    "work_dir": "",
    "interface": {
      "protocol": "",
      "types": []
    }
  }
}
```

---

### Inspect Plugin

Inspects a Docker plugin.

### Method

`docker.plugin.inspect(name: str)`

### Endpoint

N/A (This is a library function)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example
```python
from python_on_whales import docker

my_docker_plugin = docker.plugin.inspect("vieux/sshfs:latest")
```

### Response

#### Success Response (200)

Returns a `Plugin` object representing the inspected plugin.

#### Response Example
(See Install Plugin Response Example)

---

### List Plugins

Lists all Docker plugins.

### Method

`docker.plugins.list()`

### Endpoint

N/A (This is a library function)

### Parameters

None

### Request Example
```python
from python_on_whales import docker

list_of_plugins = docker.plugins.list()
```

### Response

#### Success Response (200)

Returns a list of `Plugin` objects.

#### Response Example
```json
[
  {
    "id": "7623cab41f3c65434b33fd90abbf8de9a723f2528473527507d3d4effaffd581",
    "name": "mochoa/s3fs-volume-plugin:latest",
    "enabled": true,
    "settings": {
      "mounts": [],
      "env": [
        "AWSACCESSKEYID=",
        "AWSSECRETACCESSKEY=",
        "DEFAULT_S3FSOPTS=nomultipart,use_path_request_style"
      ],
      "args": [],
      "devices": [
        {
          "name": null,
          "path": null,
          "description": null
        }
      ]
    },
    "plugin_reference": "docker.io/mochoa/s3fs-volume-plugin:latest",
    "config": {
      "docker_version": "19.03.15",
      "description": "S3FS plugin for Docker v2.0.9",
      "documentation": "https://github.com/marcelo-ochoa/docker-volume-plugins/",
      "entrypoint": [
        "/usr/bin/tini",
        "--",
        "/s3fs-volume-plugin"
      ],
      "work_dir": "",
      "interface": {
        "protocol": "",
        "types": []
      }
    }
  }
]
```
```

--------------------------------

### PluginCLI - List Plugins

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/plugin

Retrieves a list of all installed Docker plugins.

```APIDOC
## GET /plugins/list

### Description
Returns a `List[python_on_whales.Plugin]` that are installed on the daemon.

### Method
GET

### Endpoint
/plugins/list

### Response
#### Success Response (200)
- **plugins** (List[python_on_whales.Plugin]) - A list of installed plugin objects.

#### Response Example
```json
[
  {
    "id": "plugin-id-1",
    "name": "plugin-1"
  },
  {
    "id": "plugin-id-2",
    "name": "plugin-2"
  }
]
```
```

--------------------------------

### Inspect Pod Attributes

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/pods

Example demonstrating the structure and data types of various pod attributes retrieved via inspection.

```python
In [1]: from python_on_whales import DockerClient

In [2]: podman = DockerClient(client_call=["podman"])

In [3]: pod = podman.pod.create("my-pod")

In [4]: def super_print(obj):
   ...:     print(f"type={type(obj)}, value={obj}")
   ...:

In [5]: super_print(pod.id)
type = <class 'str'>, value = 1e8c42cf47b693755334b82baa69d596cf487a60774e3df25f46417979ff420a

In [6]: super_print(pod.name)
type = <class 'str'>, value = my-pod

In [7]: super_print(pod.created)
type = <class 'datetime.datetime'>, value = 2026-03-09 14:18:11.782050+00:00

In [8]: super_print(pod.state)
type = <class 'str'>, value = Created

In [9]: super_print(pod.num_containers)
type = <class 'int'>, value = 1

In [10]: super_print(pod.infra_container_id)
type = <class 'str'>, value = 0c1d141f38867b9cdd281542e5838c79a05dc74a36c9ebe54f8c956bb59e88ea

In [11]: super_print(pod.shared_namespaces)
type = <class 'list'>, value = ['ipc', 'net', 'uts']

In [12]: super_print(pod.hostname)
type = <class 'str'>, value = 

In [13]: super_print(pod.exit_policy)
type = <class 'str'>, value = continue
```

--------------------------------

### Initialize Docker Client

Source: https://gabrieldemarmiesse.github.io/python-on-whales/docker_client

Demonstrates two ways to initialize the Docker client: using the default instance or creating a new DockerClient object.

```python
from python_on_whales import docker
print(docker.run("hello-world"))
```

```python
from python_on_whales import DockerClient
docker = DockerClient()
print(docker.run("hello-world"))
```

--------------------------------

### Get Docker Buildx Version

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/buildx

Retrieves the installed Docker Buildx version. This is useful for verifying the installation and checking compatibility.

```python
from python_on_whales import docker

version = docker.buildx.version()
print(version)
# "github.com/docker/buildx v0.4.2 fb7b670b764764dc4716df3eba07ffdae4cc47b2"
```

--------------------------------

### Pod Management API

Source: https://gabrieldemarmiesse.github.io/python-on-whales/objects/pods

This section covers the core methods for interacting with Podman pods, such as creating, inspecting, starting, stopping, and removing them.

```APIDOC
## Pod Management

### Description
Provides methods to manage Podman pods.

### Methods

#### `create(name: str)`
Creates a new pod with the specified name.

#### `inspect(name: str)`
Inspects an existing pod and returns its details.

#### `exists(name: str)`
Checks if a pod with the given name exists.

#### `start()`
Starts the pod.

#### `stop(*, time: Optional[int] = None)`
Stops the pod. The `time` parameter specifies the time in seconds to wait before killing the pod.

#### `restart()`
Restarts the pod.

#### `kill(*, signal: Optional[str] = None)`
Kills the pod. The `signal` parameter specifies the signal to send.

#### `pause()`
Pauses the pod.

#### `unpause()`
Unpauses the pod.

#### `remove(*, force: bool = False, time: Optional[int] = None)`
Removes the pod. `force` can be used to force removal. `time` specifies the time in seconds to wait before killing the pod.

#### `logs(container: Optional[str] = None, *, names: bool = False, since: Optional[str] = None, tail: Optional[str] = None, timestamps: bool = False, until: Optional[str] = None, follow: bool = False, stream: bool = False)`
Retrieves logs from the pod's containers. Various options are available to filter and format the logs.

### Example Usage
```python
from python_on_whales import DockerClient

podman = DockerClient(client_call=["podman"])

# Create a pod
pod = podman.pod.create("my-pod-name")

# Inspect a pod
my_pod = podman.pod.inspect("my-pod-name")

# Check if a pod exists
if podman.pod.exists("my-pod-name"):
    print("Pod exists")

# Start a pod
podman.pod.start()

# Stop a pod
podman.pod.stop(time=10)

# Remove a pod
podman.pod.remove(force=True)
```
```

--------------------------------

### Get Docker Stack Tasks

Source: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/stack

Retrieves the list of swarm tasks for a given stack. The stack can be specified by its name or as a python_on_whales.Stack object. Example shows how to print the desired state of the first task.

```python
from python_on_whales import docker

tasks = docker.stack.ps("my-stack")
print(tasks[0].desired_state)
# running
```

--------------------------------

### Run Postgres with Volumes and Configuration

Source: https://gabrieldemarmiesse.github.io/python-on-whales

Configures a container with multiple volumes and custom database startup arguments.

```bash
docker run -d --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -e PGDATA=/var/lib/postgresql/data/pgdata -v /custom/mount:/var/lib/postgresql/data -v myvolume:/tmp/myvolume postgres -c shared_buffers=256MB -c max_connections=200
```

```python
from python_on_whales import docker

docker.run(
    "postgres:9.6",
    ["-c", "shared_buffers=256MB", "-c", "max_connections=200"],
    name="some-postgres",
    envs={"POSTGRES_PASSWORD": "mysecretpassword", "PGDATA": "/var/lib/postgresql/data/pgdata"},
    volumes=[("/custom/mount", "/var/lib/postgresql/data"), ("myvolume", "/tmp/myvolume")],
    detach=True,
)
```

--------------------------------

### Initialize Docker Client

Source: https://gabrieldemarmiesse.github.io/python-on-whales

Import the docker client to begin executing commands.

```python
from python_on_whales import docker
```

--------------------------------

### Run Hello World Container

Source: https://gabrieldemarmiesse.github.io/python-on-whales

Execute a basic docker run command and capture the output.

```python
>>> from python_on_whales import docker

>>> output = docker.run("hello-world")
>>> print(output)

Hello from Docker!
This message shows that your installation appears to be working correctly.

...
```
Tokens:
Raw