python-on-whales
A Docker client for Python, designed to be fun and intuitive!
Rank: #1267Downloads: 8,822,974 (30 days)Stars: 699Forks: 125
Description
<img src="https://raw.githubusercontent.com/gabrieldemarmiesse/python-on-whales/master/img/full.png" alt="logo" class="responsive" style="width: 80%; height: auto;">
Some more
A Docker client for Python, designed to be fun and intuitive!
Works on Linux, macOS and Windows, for Python 3.8 and above.
How to install?
pip install python-on-whales
See https://gabrieldemarmiesse.github.io/python-on-whales/docker_client/#the-dockerpodman-cli for instructions on installing Docker/Podman.
Some cool examples
Start by doing
from python_on_whales import docker
and then:
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()
You get the idea 🙂 it's the same as the CLI we all know and love.
>>> 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
Some more docker.run() advanced examples with postgres
docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres
becomes
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
becomes
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
becomes
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,
)
Any Docker object can be used as a context manager to ensure it's removed even if an exception occurs:
from python_on_whales import docker
with docker.volume.create("random_name") as some_volume:
docker.run(
"postgres:9.6",
["-c",