pywhales
Use the installed pywhales package to automate Docker from Python applications and scripts. Use when translating docker run/build/compose commands into Python, managing containers or images with pywhales, using Buildx or Compose from Python, or troubleshooting pywhales usage, output types, streaming, and cleanup. This skill is for consuming pywhales, not developing or contributing to the library.
Resources
1Install
npx skillscat add maraclaw/photon/pywhales Install via the SkillsCat registry.
PyWhales
Use the Python API that wraps the Docker CLI. Don't substitute Docker SDK APIs
or treat the pywhales console command as a Docker command runner.
Work in the user's application or script with the installed package. A PyWhales
repository checkout, changes to its internals, and its contributor test suite
are not part of this workflow.
Workflow
- Identify the target context or host, project, input paths, and desired result.
Keep existing resources separate from disposable resources the task creates. - Read the relevant reference below, not the whole bundle.
- Check the installed method with
inspect.signature()andhelp()before
adding unfamiliar arguments. These checks need no repository checkout or
running engine. - Translate commands into argument sequences and verified keyword arguments.
Choose captured output, detached objects, or streaming before writing code. - Scope clients instead of changing the user's active Docker context. Give owned
containers and streams explicit lifetimes; don't attach cleanup to borrowed objects. - Validate the smallest authorized scenario. Report what ran, its output type,
cleanup, and any unavailable engine or plugin checks.
Topic Router
| Read when | Reference |
|---|---|
| Setting up imports, local/remote clients, CLI prerequisites, or handling errors | Client, setup, and errors |
| Translating run/exec/ps, choosing output modes, mounting files, or cleaning up containers and streams | Containers, output, and lifecycle |
| Building images, selecting exporters, streaming builds, or checking Dockerfiles | Buildx |
| Selecting Compose files/projects, building services, running jobs, or managing a stack | Compose |
| Checking installed API support and verifying the user's automation | Usage validation |
Quick Translation
| Docker CLI intent | PyWhales entry point |
|---|---|
docker run ... |
docker.run(image, ["arg", ...], ...) |
docker exec ... |
docker.execute(container, ["arg", ...]), not docker.exec |
docker ps |
docker.ps() or docker.container.list() |
docker build ... |
docker.build(...), an alias of docker.buildx.build(...) |
docker compose ... |
A scoped DockerClient(...).compose namespace |
Pass commands as lists, not shell command strings. Use a shell inside the
container only when the task actually requires shell syntax. A detached run
returns a Container, not logs; a build doesn't always return a local Image.
Read the relevant output contract before consuming either result.
Install
npx skillscat add maraclaw/photon/pywhales Install via the SkillsCat registry.
Repository Stars
The star count shown is for the parent repository (MaraClaw/Photon), not this specific skill.
.agents/skills/pywhales