python-on-whales 0.73.0

Python的Docker客户端，设计得有趣且直观！

适用于Linux、macOS和Windows，Python 3.8及以上版本。

• 文档
• Github仓库

如何安装？

pip install python-on-whales

一些有趣的例子

首先

from python_on_whales import docker

然后

• docker run hello-world -> docker.run("hello-world")
• docker pull ubuntu -> docker.pull("ubuntu")
• docker build ./ -> docker.build("./")
• docker compose up my_service -> docker.compose.up(["my_service"])
• docker image ls -> docker.image.list()
• docker ps -> docker.ps()
• docker cp -> docker.copy()

明白了 😄，和我们都熟悉和喜爱的 CLI 一样。

>>> 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.

...

>>> from python_on_whales import docker
>>> print(docker.run("nvidia/cuda:11.0-base", ["nvidia-smi"], gpus="all"))
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 450.51.06    Driver Version: 450.51.06    CUDA Version: 11.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  Tesla T4            On   | 00000000:00:1E.0 Off |                    0 |
| N/A   34C    P8     9W /  70W |      0MiB / 15109MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+

+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+

>>> from python_on_whales import docker
>>> my_docker_image = docker.pull("ubuntu:20.04")
20.04: Pulling from library/ubuntu
e6ca3592b144: Downloading [=============>                                     ]  7.965MB/28.56MB
534a5505201d: Download complete
990916bd23bb: Download complete

>>> print(my_docker_image.repo_tags)
['ubuntu:20.04']

>>> docker.image.list()
[python_on_whales.Image(id='sha256:1a437e363abfa', tags=['ubuntu:20.04'])]

>>> my_docker_image.remove()

>>> from python_on_whales import docker
>>> my_image = docker.build(".", tags="some_name")  # uses Buildx/buildkit by default
[+] Building 1.6s (17/17) FINISHED
 => [internal] load build definition from Dockerfile                                                            0.0s
 => => transferring dockerfile: 32B                                                                             0.0s
 => [internal] load .dockerignore                                                                               0.0s
 => => transferring context: 2B                                                                                 0.0s
 => [internal] load metadata for docker.io/library/python:3.6                                                   1.4s
 => [python_dependencies 1/5] FROM docker.io/library/python:3.6@sha256:29328c59adb9ee6acc7bea8eb86d0cb14033c85  0.0s
 => [internal] load build context                                                                               0.1s
 => => transferring context: 72.86kB                                                                            0.0s
 => CACHED [python_dependencies 2/5] RUN pip install typeguard pydantic requests tqdm                           0.0s
 => CACHED [python_dependencies 3/5] COPY tests/test-requirements.txt /tmp/                                     0.0s
 => CACHED [python_dependencies 4/5] COPY requirements.txt /tmp/                                                0.0s
 => CACHED [python_dependencies 5/5] RUN pip install -r /tmp/test-requirements.txt -r /tmp/requirements.txt     0.0s
 => CACHED [tests_ubuntu_install_without_buildx 1/7] RUN apt-get update &&     apt-get install -y       apt-tr  0.0s
 => CACHED [tests_ubuntu_install_without_buildx 2/7] RUN curl -fsSL https://download.docker.com/linux/ubuntu/g  0.0s
 => CACHED [tests_ubuntu_install_without_buildx 3/7] RUN add-apt-repository    "deb [arch=amd64] https://downl  0.0s
 => CACHED [tests_ubuntu_install_without_buildx 4/7] RUN  apt-get update &&      apt-get install -y docker-ce-  0.0s
 => CACHED [tests_ubuntu_install_without_buildx 5/7] WORKDIR /python-on-whales                                  0.0s
 => CACHED [tests_ubuntu_install_without_buildx 6/7] COPY . .                                                   0.0s
 => CACHED [tests_ubuntu_install_without_buildx 7/7] RUN pip install -e .                                       0.0s
 => exporting to image                                                                                          0.1s
 => => exporting layers                                                                                         0.0s
 => => writing image sha256:e1c2382d515b097ebdac4ed189012ca3b34ab6be65ba0c650421ebcac8b70a4d                    0.0s
 => => naming to docker.io/library/some_image_name

一些更高级的 docker.run() 例子，以 postgres 为例

docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres

变为

from python_on_whales import docker

docker.run(
    "postgres:9.6",
    name="some-postgres",
    envs={"POSTGRES_PASSWORD": "mysecretpassword"},
    detach=True,
)
print(docker.ps())
# [python_on_whales.Container(id='f5fb939c409d', name='some-postgres')]

docker run -it --rm --network some-network postgres psql -h some-postgres -U postgres

变为

from python_on_whales import docker

# since it's interactive, you'll be dropped into the psql shell. The python code
# will continue only after you exit the shell.
docker.run(
    "postgres:9.6",
    ["psql", "-h", "some-postgres", "-U", "postgres"],
    networks=["some-network"],
    interactive=True,
    tty=True,
    remove=True,
)

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

变为

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,
)

任何 Docker 对象都可以用作上下文管理器，以确保即使在发生异常的情况下也能将其删除

from python_on_whales import docker

with docker.volume.create("random_name") as some_volume:
    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=[(some_volume, "/var/lib/postgresql/data"), ("myvolume", "/tmp/myvolume")],
        detach=True,
    )
    # so some stuff here
    
# here we are out of the context manager, so the volume has been removed, even if there was an exception.

主要功能

• CLI 接口与 Python API 之间的一对一映射。不需要查阅文档来查找所需的函数/参数名称。
• 支持最新的 Docker 功能： Docker buildx/buildkit、docker run --gpu=all ...
• 支持 Docker stack、services 和 Swarm（与命令行相同的 API）。
• 在拉取、推送、加载、构建时显示进度条和渐进式输出
• 支持一些不在 Docker-py 中的 CLI 命令： docker cp、docker run --cpus ... 等。
• 对远程守护进程的出色 SSH 支持。
• Docker 对象作为 Python 对象：容器、镜像、卷、服务...，它们的属性会实时更新！
• 每个 Docker 对象都可以用作上下文管理器。退出上下文时，Docker 对象将自动删除，即使发生异常。
• 完全类型化的 API（兼容 Mypy 和 IDE）与 pathlib 和 os.path 兼容
• 所有 Docker 对象和 Docker 客户端都适用于多线程和多进程。
• 通过设置环境变量 PYTHON_ON_WHALES_DEBUG=1 来显示调用的命令和使用的环境变量。

为什么要有另一个项目？为什么不基于 Docker-py 开发呢？

从某种意义上说，这个项目是在 Docker-py 的基础上构建的，因为实现、组织和 API 都受到了该项目的启发，但代码库不能相同。

以下两个主要差异不允许这样做

1. API 完全不同。Python on Whales 的目标是提供 Docker 命令行和 Python 之间的一对一映射，这样用户甚至不需要打开文档就能编写代码。

2. 而 Docker-py 是 Docker 客户端二进制文件的完整重实现（用 Go 编写），Python on Whales 则位于 Docker 客户端二进制文件之上，这使得实现新功能更加容易和安全。例如，docker-py 很可能不会很快支持 Buildx/buildkit，因为用 Python 重写大型 Go 代码库是一项艰巨的工作。

我应该使用 Docker-py 还是 Python on Whales？

项目的描述中都有说明！

• Docker-py：Docker 引擎 API 的 Python 库
• Python on Whales：出色的 Docker CLI 的 Python 包装器

如果您需要直接与 Docker 引擎通信，需要进行低级操作，则使用 docker-py。一些好的例子包括在 IDE 中控制 docker 的代码或当 Docker 调用的速度非常重要时。如果您不想依赖 Docker CLI 二进制文件（约 50MB），则使用 docker-py。

如果您想从 Python 调用 docker 命令行，执行高级操作，则使用 Python on Whales。例如，如果您想在 Python 中而不是在 bash 中编写 CI 逻辑（这是一个非常好的选择 😉）。一些命令仅适用于 Python on Whales：docker.buildx.build(...)、docker.stack.deploy(...)...

为正确的工作使用正确的工具 😄

Docker 的替代方案：Podman、nerdctl...

从 Python-on-whales 版本 0.44.0 开始引入了对 Docker 兼容客户端（如 Podman 和 Nerdctl）的支持。

您可以使用任意二进制文件通过使用 python_on_whales.DockerCLient 的 client_call 参数来执行 Docker 命令。以下是一个示例

>>> from python_on_whales import DockerClient

>>> nerdctl = DockerClient(client_call=["nerdctl"])

>>> nerdctl.pull("python:3.9")
docker.io/library/python:3.9:                                                     resolved       |++++++++++++++++++++++++++++++++++++++|
index-sha256:a83c0aa6471527636d7331c30704d0f88e0ab3331bbc460d4ae2e53bbae64dca:    done           |++++++++++++++++++++++++++++++++++++++|
manifest-sha256:8ccef93ff3c9e1bb9562d394526cdc6834033a0498073d41baa8b309f4fac20e: done           |++++++++++++++++++++++++++++++++++++++|
config-sha256:f033692e2c5abe1e0ee34bcca759a3e4432b10b0031174b08d48bcc90d14d68b:   done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:9952b1051adaff513c99f86765361450af108b12b0073d0ba40255c4e419b481:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:c766e27afb21eddf9ab3e4349700ebe697c32a4c6ada6af4f08282277a291a28:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:1535e3c1181a81ea66d5bacb16564e4da2ba96304506598be39afe9c82b21c5c:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:6de7cb7bdc8f9b4c4d6539233fe87304aa1a6427c3238183265c9f02d831eddb:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:967757d5652770cfa81b6cc7577d65e06d336173da116d1fb5b2d349d5d44127:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:c357e2c68cb3bf1e98dcb3eb6ceb16837253db71535921d6993c594588bffe04:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:26787c68cf0c92a778db814d327e283fe1da4434a7fea1f0232dae8002e38f33:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:6aefca2dc61dcbcd268b8a9861e552f9cdb69e57242faec64ac120d2355a9c1a:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:32a180f5cf85702e7680719c40c39c07972b1176355df5a621de9eb87ad07ce2:    done           |++++++++++++++++++++++++++++++++++++++|
elapsed: 35.9s                                                                    total:  333.5  (9.3 MiB/s)

python_on_whales.Image(id='sha256:f033692e2c5ab', tags=['python:3.9'])

您可以使用 podman 执行类似操作

from python_on_whales import DockerClient

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

podman.pull("hello-world")
podman.run("hello-world")
print(podman.ps())
...

贡献

所有贡献都受欢迎。请参阅此文档。

关于许可证呢？

这是一个MIT许可证，因此非常宽松。

许可证可以在git仓库中找到。