zuke.tools.docker_compose

@zuke/docker-compose 1.3.1: @zuke/docker-compose — typed Docker Compose task wrappers for Zuke builds.

Symbols

DockerComposeBuildSettings

class

class DockerComposeBuildSettings(DockerComposeSettings)

Settings for compose build.

no_cache() -> Self
Do not use the layer cache (--no-cache).
pull() -> Self
Always attempt to pull newer base images (--pull).
build_arg(key: str, value: str) -> Self
Pass a build-time variable (--build-arg KEY=value); repeatable.
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposeCommitSettings

class

class DockerComposeCommitSettings(DockerComposeSettings)

Settings for compose commit.

service(name: str) -> Self
The service whose container to commit (required).
reference(value: str) -> Self
The image reference to create, e.g. my-app:test.
author(value: str) -> Self
Image author (--author).
message(value: str) -> Self
Commit message (--message).
change(*instructions: str) -> Self
Apply a Dockerfile instruction to the created image (--change).
index(value: float) -> Self
Pick the replica to commit when the service has several (--index).
no_pause() -> Self
Leave the container running during the commit (--pause=false). Compose pauses it by default so the filesystem cannot change mid-capture; turning that off trades a consistent image for uninterrupted service.

DockerComposeConfigSettings

class

class DockerComposeConfigSettings(DockerComposeSettings)

Settings for compose config.

quiet_output() -> Self
Only validate, printing nothing (-q).
services_only() -> Self
Print the service names only (--services).
volumes_only() -> Self
Print the volume names only (--volumes).
format(value: str) -> Self
Output format (--format), e.g. yaml or json.

DockerComposeCpSettings

class

class DockerComposeCpSettings(DockerComposeSettings)

Settings for compose cp.

Compose copies between a service container and the local filesystem, so exactly one side names a service. Naming both or neither is refused rather than handed to Compose as a path it cannot resolve.

from_service(service: str, path: str) -> Self
Copy out of service at path (SERVICE:PATH).
from_local(path: str) -> Self
Copy out of a local path.
to_service(service: str, path: str) -> Self
Copy into service at path (SERVICE:PATH).
to_local(path: str) -> Self
Copy into a local path.
index(value: float) -> Self
Pick the replica to copy from when the service has several (--index).
all() -> Self
Include containers created by compose run (--all).
archive() -> Self
Preserve uid/gid information (--archive).
follow_link() -> Self
Follow symbolic links in the source path (--follow-link).

DockerComposeCreateSettings

class

class DockerComposeCreateSettings(DockerComposeSettings)

Settings for compose create.

services(*names: str) -> Self
Restrict creation to these services.
build() -> Self
Build images before creating containers (--build).
no_build() -> Self
Never build, whatever the policy says (--no-build).
force_recreate() -> Self
Recreate containers even when their configuration has not changed (--force-recreate).
no_recreate() -> Self
Leave existing containers in place (--no-recreate).
remove_orphans() -> Self
Remove containers for services no longer in the file (--remove-orphans).
quiet_pull() -> Self
Pull without progress output (--quiet-pull).
pull(policy: Literal['always', 'missing', 'never']) -> Self
When to pull images before creating (--pull).
scale(service: str, replicas: float) -> Self
Create replicas containers for service (--scale).
yes() -> Self
Answer every prompt affirmatively (--yes), so an unattended run cannot stall.

DockerComposeDownSettings

class

class DockerComposeDownSettings(DockerComposeSettings)

Settings for compose down.

volumes() -> Self
Also remove named and anonymous volumes (-v).
remove_orphans() -> Self
Remove containers for services no longer defined (--remove-orphans).
rmi(type_: str) -> Self
Remove images of the given type (--rmi), e.g. all or local.
timeout(seconds: float) -> Self
Shutdown timeout in seconds (-t).

DockerComposeEventsSettings

class

class DockerComposeEventsSettings(DockerComposeSettings)

Settings for compose events.

services(*names: str) -> Self
Restrict the stream to these services.
json() -> Self
Emit each event as a JSON object (--json).
since(timestamp: str) -> Self
Include events since a timestamp (--since).
until(timestamp: str) -> Self
Stop streaming at a timestamp (--until). Without it the command streams until interrupted, so a build target that awaits it blocks — bound the run with this or with .killAfter(ms).

DockerComposeExecSettings

class

class DockerComposeExecSettings(DockerComposeSettings)

Settings for compose exec.

service(name: str) -> Self
The service whose container to exec into (required).
detach() -> Self
Run in the background (-d).
no_tty() -> Self
Disable pseudo-TTY allocation (-T).
workdir(path: str) -> Self
Working directory inside the container (-w).
env_var(key: str, value: str) -> Self
Set an environment variable (-e KEY=value); repeatable.
command_args(*args: str | float) -> Self
The command and arguments to execute.

DockerComposeExportSettings

class

class DockerComposeExportSettings(DockerComposeSettings)

Settings for compose export.

service(name: str) -> Self
The service whose container filesystem to export (required).
output(path: str) -> Self
Write the tar archive to a file (--output) instead of stdout. Prefer it: a tar stream captured as the command's stdout goes through Zuke's output buffer, which is text-shaped and size-capped.
index(value: float) -> Self
Pick the replica to export when the service has several (--index).

DockerComposeImagesSettings

class

class DockerComposeImagesSettings(DockerComposeListingSettings)

Settings for compose images.

services(*names: str) -> Self
Restrict the listing to these services.

DockerComposeKillSettings

class

class DockerComposeKillSettings(DockerComposeSettings)

Settings for compose kill.

services(*names: str) -> Self
Restrict the kill to these services.
signal(name: str) -> Self
The signal to send (--signal), SIGKILL by default. Send SIGTERM to let a service run its shutdown path — kill skips the grace period stop gives it.
remove_orphans() -> Self
Remove containers for services no longer in the file (--remove-orphans).

DockerComposeListingSettings

class

class DockerComposeListingSettings(DockerComposeSettings)

Shared by the listing subcommands that accept --format and --quiet.

--format json is what makes these readable by a build rather than by a person, so the convenience json spells it rather than leaving the caller to remember the value.

format(value: str) -> Self
Format the output (--format), e.g. table or json.
json() -> Self
Emit JSON (--format json).
quiet_output() -> Self
Print only identifiers or names (--quiet).

DockerComposeLogsSettings

class

class DockerComposeLogsSettings(DockerComposeSettings)

Settings for compose logs.

follow() -> Self
Stream new log output (-f).
timestamps() -> Self
Prefix each line with a timestamp (-t).
tail(lines: Literal['all'] | float) -> Self
Show only the last N lines, or all (--tail).
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposeLsSettings

class

class DockerComposeLsSettings(DockerComposeListingSettings)

Settings for compose ls, which lists Compose projects rather than services.

all() -> Self
Include stopped projects (--all).
filter(expression: str) -> Self
Filter the listing (--filter), e.g. name=my-project.

DockerComposePauseSettings

class

class DockerComposePauseSettings(DockerComposeServiceListSettings)

Settings for compose pause.

DockerComposePortSettings

class

class DockerComposePortSettings(DockerComposeSettings)

Settings for compose port, which prints the host address a service's container port was published on.

service(name: str) -> Self
The service to ask about (required).
private_port(port: float) -> Self
The container-side port to look up (required).
protocol(value: Literal['tcp', 'udp']) -> Self
The protocol of the binding (--protocol), tcp by default.
index(value: float) -> Self
Pick the replica to ask when the service has several (--index).

DockerComposePsSettings

class

class DockerComposePsSettings(DockerComposeSettings)

Settings for compose ps.

all() -> Self
Show stopped containers too (-a).
quiet_output() -> Self
Only show container IDs (-q).
services_only() -> Self
Display services instead of containers (--services).
format(value: str) -> Self
Output format (--format): table, json, or a Go template such as {{.Image}}, which prints one line per container.
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposePullSettings

class

class DockerComposePullSettings(DockerComposeSettings)

Settings for compose pull.

ignore_pull_failures() -> Self
Continue past services whose pull fails (--ignore-pull-failures).
policy(value: Literal['always', 'missing', 'never']) -> Self
Which images to pull (--policy): missing skips an image already present locally — so a locally built image is not looked up in a registry — and always fetches every one.
quiet_output() -> Self
Pull without printing progress (-q).
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposePushSettings

class

class DockerComposePushSettings(DockerComposeSettings)

Settings for compose push.

ignore_push_failures() -> Self
Continue past services whose push fails (--ignore-push-failures).
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposeRestartSettings

class

class DockerComposeRestartSettings(DockerComposeSettings)

Settings for compose restart.

timeout(seconds: float) -> Self
Restart timeout in seconds (-t).
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposeRmSettings

class

class DockerComposeRmSettings(DockerComposeSettings)

Settings for compose rm.

force() -> Self
Do not prompt for confirmation (-f).
stop() -> Self
Stop the containers first if needed (-s).
volumes() -> Self
Also remove anonymous volumes (-v).
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposeRunSettings

class

class DockerComposeRunSettings(DockerComposeSettings)

Settings for compose run.

service(name: str) -> Self
The service to run (required).
rm() -> Self
Remove the container after it exits (--rm).
detach() -> Self
Run in the background (-d).
no_deps() -> Self
Do not start linked services (--no-deps).
name(value: str) -> Self
Assign a container name (--name).
env_var(key: str, value: str) -> Self
Set an environment variable (-e KEY=value); repeatable.
command_args(*args: str | float) -> Self
The command and arguments to run inside the container.

DockerComposeScaleSettings

class

class DockerComposeScaleSettings(DockerComposeSettings)

Settings for compose scale.

scale(service: str, replicas: float) -> Self
Scale service to replicas instances; repeatable (required).
no_deps() -> Self
Do not start linked services (--no-deps).

DockerComposeServiceListSettings

class

class DockerComposeServiceListSettings(DockerComposeSettings)

Settings shared by compose pause and compose unpause, which take only a service list.

services(*names: str) -> Self
Restrict the command to these services.

DockerComposeSettings

class

class DockerComposeSettings(ToolSettings)

Base for all Compose subcommand settings. Holds the invocation prefix (docker compose vs docker-compose) and the global options that precede every subcommand (-f, -p, --profile, …), and resolves the prefix at run time unless it was pinned with usePlugin/useStandalone.

file(path: str) -> Self
Add a Compose file (-f); repeatable, order-significant.
project_name(name: str) -> Self
Set the project name (-p).
profile(name: str) -> Self
Enable a service profile (--profile); repeatable.
project_directory(path: str) -> Self
Set the project working directory (--project-directory).
env_file(path: str) -> Self
Load environment from a file (--env-file).
use_plugin() -> Self
Force the v2 plugin form (docker compose) and skip detection.
use_standalone() -> Self
Force the v1 standalone form (docker-compose) and skip detection.

DockerComposeStartSettings

class

class DockerComposeStartSettings(DockerComposeSettings)

Settings for compose start.

services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposeStopSettings

class

class DockerComposeStopSettings(DockerComposeSettings)

Settings for compose stop.

timeout(seconds: float) -> Self
Shutdown timeout in seconds (-t).
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposeTasks

class

class DockerComposeTasks

Typed task functions for Docker Compose (docker compose/docker-compose).

static async up(ctx: ServiceContext, configure: Callable[[DockerComposeUpSettings], DockerComposeUpSettings] | None=None) -> ExecResult
Create and start services: compose up.
static async down(ctx: ServiceContext, configure: Callable[[DockerComposeDownSettings], DockerComposeDownSettings] | None=None) -> ExecResult
Stop and remove services: compose down.
static async build(ctx: ServiceContext, configure: Callable[[DockerComposeBuildSettings], DockerComposeBuildSettings] | None=None) -> ExecResult
Build service images: compose build.
static async pull(ctx: ServiceContext, configure: Callable[[DockerComposePullSettings], DockerComposePullSettings] | None=None) -> ExecResult
Pull service images: compose pull.
static async push(ctx: ServiceContext, configure: Callable[[DockerComposePushSettings], DockerComposePushSettings] | None=None) -> ExecResult
Push service images: compose push.
static async run(ctx: ServiceContext, configure: Callable[[DockerComposeRunSettings], DockerComposeRunSettings] | None=None) -> ExecResult
Run a one-off command: compose run.
static async exec(ctx: ServiceContext, configure: Callable[[DockerComposeExecSettings], DockerComposeExecSettings] | None=None) -> ExecResult
Exec into a running service: compose exec.
static async logs(ctx: ServiceContext, configure: Callable[[DockerComposeLogsSettings], DockerComposeLogsSettings] | None=None) -> ExecResult
View service logs: compose logs.
static async ps(ctx: ServiceContext, configure: Callable[[DockerComposePsSettings], DockerComposePsSettings] | None=None) -> ExecResult
List containers: compose ps.
static async config(ctx: ServiceContext, configure: Callable[[DockerComposeConfigSettings], DockerComposeConfigSettings] | None=None) -> ExecResult
Render the resolved configuration: compose config.
static async start(ctx: ServiceContext, configure: Callable[[DockerComposeStartSettings], DockerComposeStartSettings] | None=None) -> ExecResult
Start existing services: compose start.
static async stop(ctx: ServiceContext, configure: Callable[[DockerComposeStopSettings], DockerComposeStopSettings] | None=None) -> ExecResult
Stop running services: compose stop.
static async restart(ctx: ServiceContext, configure: Callable[[DockerComposeRestartSettings], DockerComposeRestartSettings] | None=None) -> ExecResult
Restart services: compose restart.
static async rm(ctx: ServiceContext, configure: Callable[[DockerComposeRmSettings], DockerComposeRmSettings] | None=None) -> ExecResult
Remove stopped service containers: compose rm.
static async create(ctx: ServiceContext, configure: Callable[[DockerComposeCreateSettings], DockerComposeCreateSettings] | None=None) -> ExecResult
Create containers without starting them: compose create.
static async kill(ctx: ServiceContext, configure: Callable[[DockerComposeKillSettings], DockerComposeKillSettings] | None=None) -> ExecResult
Force-stop service containers: compose kill.
static async pause(ctx: ServiceContext, configure: Callable[[DockerComposePauseSettings], DockerComposePauseSettings] | None=None) -> ExecResult
Pause services: compose pause.
static async unpause(ctx: ServiceContext, configure: Callable[[DockerComposeUnpauseSettings], DockerComposeUnpauseSettings] | None=None) -> ExecResult
Resume paused services: compose unpause.
static async scale(ctx: ServiceContext, configure: Callable[[DockerComposeScaleSettings], DockerComposeScaleSettings] | None=None) -> ExecResult
Set service replica counts: compose scale.
static async wait(ctx: ServiceContext, configure: Callable[[DockerComposeWaitSettings], DockerComposeWaitSettings] | None=None) -> ExecResult
Block until services stop: compose wait. Keeps the ordinary contract — a non-zero container status fails the target. Use DockerComposeTasksApi.waitExitCode when the status is the answer rather than a failure.
static async cp(ctx: ServiceContext, configure: Callable[[DockerComposeCpSettings], DockerComposeCpSettings] | None=None) -> ExecResult
Copy between a service container and the local filesystem: compose cp.
static async top(ctx: ServiceContext, configure: Callable[[DockerComposeTopSettings], DockerComposeTopSettings] | None=None) -> ExecResult
Show running processes: compose top.
static async export(ctx: ServiceContext, configure: Callable[[DockerComposeExportSettings], DockerComposeExportSettings] | None=None) -> ExecResult
Export a container filesystem as a tar archive: compose export.
static async commit(ctx: ServiceContext, configure: Callable[[DockerComposeCommitSettings], DockerComposeCommitSettings] | None=None) -> ExecResult
Create an image from a container: compose commit.
static async images(ctx: ServiceContext, configure: Callable[[DockerComposeImagesSettings], DockerComposeImagesSettings] | None=None) -> ExecResult
List the images the containers use: compose images.
static async volumes(ctx: ServiceContext, configure: Callable[[DockerComposeVolumesSettings], DockerComposeVolumesSettings] | None=None) -> ExecResult
List the project's volumes: compose volumes.
static async ls(ctx: ServiceContext, configure: Callable[[DockerComposeLsSettings], DockerComposeLsSettings] | None=None) -> ExecResult
List Compose projects: compose ls.
static async version(ctx: ServiceContext, configure: Callable[[DockerComposeVersionSettings], DockerComposeVersionSettings] | None=None) -> ExecResult
Report the Compose version: compose version.
static async port(ctx: ServiceContext, configure: Callable[[DockerComposePortSettings], DockerComposePortSettings] | None=None) -> ExecResult
Print a published port binding: compose port.
static async events(ctx: ServiceContext, configure: Callable[[DockerComposeEventsSettings], DockerComposeEventsSettings] | None=None) -> ExecResult
Stream container events: compose events.
static async wait_exit_code(ctx: ServiceContext, configure: Callable[[DockerComposeWaitSettings], DockerComposeWaitSettings] | None=None) -> object
The exit status the waited-on container stopped with. compose wait exits with the container's own status, so every code is a legitimate answer and none is left to mean "compose broke". This hands the code back rather than failing the target, and still fails when compose never reached a container at all.
static async service_port(ctx: ServiceContext, configure: Callable[[DockerComposePortSettings], DockerComposePortSettings] | None=None) -> object
The host port a service's container port was published on. The point of letting Compose pick an ephemeral port is asking which one it picked, which is what this returns.
static async compose_version(ctx: ServiceContext, configure: Callable[[DockerComposeVersionSettings], DockerComposeVersionSettings] | None=None) -> object
The installed Compose version, parsed from compose version --format json.

DockerComposeTopSettings

class

class DockerComposeTopSettings(DockerComposeSettings)

Settings for compose top.

services(*names: str) -> Self
Restrict the report to these services.

DockerComposeUnpauseSettings

class

class DockerComposeUnpauseSettings(DockerComposeServiceListSettings)

Settings for compose unpause.

DockerComposeUpSettings

class

class DockerComposeUpSettings(DockerComposeSettings)

Settings for compose up.

detach() -> Self
Run in the background (-d).
build() -> Self
Build images before starting (--build).
force_recreate() -> Self
Recreate containers even if unchanged (--force-recreate).
no_recreate() -> Self
Leave containers that already exist as they are, even when their configuration changed (--no-recreate). Scaling a service with it only adds or removes replicas; the ones already running keep their image.
remove_orphans() -> Self
Remove containers for services no longer defined (--remove-orphans).
wait() -> Self
Wait until services are running/healthy (--wait).
abort_on_container_exit() -> Self
Stop all containers if any container stops (--abort-on-container-exit).
no_deps() -> Self
Start only the named services, leaving their dependencies alone (--no-deps). Without it compose starts or recreates a dependency that is stopped or whose configuration changed. With an already-healthy stack the two agree, so the difference shows up only on the runs where a dependency was not ready — which is where a target that meant "just this service" wants to be explicit.
pull(policy: Literal['always', 'missing', 'never']) -> Self
When to fetch images before starting (--pull). always keeps a stack on the current published images rather than whatever was pulled last; missing fetches only what is absent locally; never uses what is there. Distinct from DockerComposeBuildSettings.pull, which is build --pull, and from the pull task, which is the subcommand — each mirrors its own command.
exit_code_from(service: str) -> Self
Exit with this service's container's exit code (--exit-code-from).
scale(service: str, instances: float) -> Self
Scale a service to N instances (--scale service=N); repeatable.
services(*names: str) -> Self
Restrict to specific services (positional); optional.

DockerComposeVersionSettings

class

class DockerComposeVersionSettings(DockerComposeSettings)

Settings for compose version.

format(value: str) -> Self
Format the output (--format), pretty or json.
json() -> Self
Emit JSON (--format json).
short() -> Self
Print only the version number (--short).

DockerComposeVolumesSettings

class

class DockerComposeVolumesSettings(DockerComposeListingSettings)

Settings for compose volumes.

services(*names: str) -> Self
Restrict the listing to the volumes these services use.

DockerComposeWaitSettings

class

class DockerComposeWaitSettings(DockerComposeSettings)

Settings for compose wait.

The command blocks until the named services' containers stop, then exits with the first container's own exit status. That makes its exit code a result rather than a failure — see DockerComposeTasks.waitExitCode, which hands the code back instead of failing the target.

services(*names: str) -> Self
The services to wait on (required).
down_project() -> Self
Tear the project down once the first container stops (--down-project), so a test run cleans up after itself without a second command.