tessl/pypi-python-on-whales

A Docker client for Python, designed to be fun and intuitive!

—

Pending

Overview

Eval results

Files

Docker Compose

Name: tessl/pypi-python-on-whales
Author: tessl

Complete Docker Compose support for multi-container application orchestration. Docker Compose enables defining and running multi-container applications using YAML configuration files.

Capabilities

Application Lifecycle Management

Start, stop, and manage multi-container applications defined in Compose files.

def up(
    services: Optional[List[str]] = None,
    *,
    detach: bool = False,
    build: bool = False,
    no_build: bool = False,
    pull: Optional[str] = None,
    no_deps: bool = False,
    force_recreate: bool = False,
    no_recreate: bool = False,
    no_start: bool = False,
    scale: Optional[Dict[str, int]] = None,
    abort_on_container_exit: bool = False,
    timeout: Optional[int] = None,
    remove_orphans: bool = False,
    profiles: Optional[List[str]] = None
) -> None:
    """
    Create and start containers for services.
    
    Parameters:
    - services: Specific services to start
    - detach: Run in background
    - build: Build images before starting
    - no_build: Don't build missing images
    - pull: Pull policy (always, missing, never)
    - no_deps: Don't start linked services
    - force_recreate: Recreate containers even if unchanged
    - no_recreate: Don't recreate existing containers
    - no_start: Don't start services after creating
    - scale: Service scaling (service_name: replica_count)
    - abort_on_container_exit: Stop all containers if any exits
    - timeout: Shutdown timeout in seconds
    - remove_orphans: Remove containers for services not in Compose file
    - profiles: Specify service profiles to enable
    """

def down(
    *,
    remove_orphans: bool = False,
    volumes: bool = False,
    rmi: Optional[str] = None,
    timeout: Optional[int] = None
) -> None:
    """
    Stop and remove containers and networks.
    
    Parameters:
    - remove_orphans: Remove containers for services not in Compose file
    - volumes: Remove named volumes and anonymous volumes
    - rmi: Remove images (all, local)
    - timeout: Shutdown timeout in seconds
    """

def start(services: Optional[List[str]] = None) -> None:
    """
    Start existing containers for services.
    
    Parameters:
    - services: Specific services to start
    """

def stop(
    services: Optional[List[str]] = None,
    *,
    timeout: Optional[int] = None
) -> None:
    """
    Stop running containers without removing them.
    
    Parameters:
    - services: Specific services to stop
    - timeout: Shutdown timeout in seconds
    """

def restart(
    services: Optional[List[str]] = None,
    *,
    timeout: Optional[int] = None
) -> None:
    """
    Restart services.
    
    Parameters:
    - services: Specific services to restart
    - timeout: Shutdown timeout in seconds
    """

Service Management

Pause, unpause, and scale services within Compose applications.

def pause(services: Optional[List[str]] = None) -> None:
    """
    Pause services (suspend all processes).
    
    Parameters:
    - services: Specific services to pause
    """

def unpause(services: Optional[List[str]] = None) -> None:
    """
    Unpause services.
    
    Parameters:
    - services: Specific services to unpause
    """

def kill(
    services: Optional[List[str]] = None,
    *,
    signal: str = "SIGKILL"
) -> None:
    """
    Kill containers for services.
    
    Parameters:
    - services: Specific services to kill
    - signal: Signal to send
    """

Build Operations

Build and rebuild images for Compose services.

def build(
    services: Optional[List[str]] = None,
    *,
    build_args: Optional[Dict[str, str]] = None,
    no_cache: bool = False,
    pull: bool = False,
    parallel: bool = True,
    progress: str = "auto",
    quiet: bool = False
) -> None:
    """
    Build or rebuild services.
    
    Parameters:
    - services: Specific services to build
    - build_args: Build-time variables
    - no_cache: Don't use cache when building
    - pull: Always pull newer version of base image
    - parallel: Build images in parallel
    - progress: Progress output type (auto, plain, tty)
    - quiet: Don't print build output
    """

Service Inspection and Monitoring

List services, view logs, and monitor service status.

def ps(
    services: Optional[List[str]] = None,
    *,
    all: bool = False,
    filter: Optional[str] = None,
    format: Optional[str] = None,
    quiet: bool = False,
    services_filter: bool = False,
    status: Optional[List[str]] = None
) -> List[Container]:
    """
    List containers for services.
    
    Parameters:
    - services: Specific services to list
    - all: Show all containers (including stopped)
    - filter: Filter containers by state
    - format: Output format
    - quiet: Only show container IDs
    - services_filter: Show only services
    - status: Filter by container status
    
    Returns:
    - List of Container objects
    """

def logs(
    services: Optional[List[str]] = None,
    *,
    follow: bool = False,
    tail: Optional[int] = None,
    since: Optional[str] = None,
    until: Optional[str] = None,
    timestamps: bool = False,
    no_color: bool = False
) -> str:
    """
    View output from services.
    
    Parameters:
    - services: Specific services to show logs for
    - follow: Follow log output
    - tail: Number of lines from end of logs
    - since: Show logs since timestamp
    - until: Show logs until timestamp
    - timestamps: Show timestamps
    - no_color: Disable colored output
    
    Returns:
    - Log output string
    """

def top(services: Optional[List[str]] = None) -> Dict[str, List[Dict[str, str]]]:
    """
    Display running processes for services.
    
    Parameters:
    - services: Specific services to show processes for
    
    Returns:
    - Dictionary mapping service names to process lists
    """

Configuration and Validation

View and validate Compose configurations.

def config(
    *,
    resolve_image_digests: bool = False,
    no_interpolate: bool = False,
    quiet: bool = False,
    profiles: Optional[List[str]] = None,
    services: Optional[List[str]] = None,
    volumes: bool = False,
    hash: Optional[str] = None
) -> str:
    """
    Parse, resolve and render Compose file in canonical format.
    
    Parameters:
    - resolve_image_digests: Pin image tags to digests
    - no_interpolate: Don't interpolate environment variables
    - quiet: Only validate configuration
    - profiles: Specify service profiles to include
    - services: Print service names
    - volumes: Print volume names
    - hash: Print service config hash
    
    Returns:
    - Compose configuration as YAML string
    """

def version() -> Dict[str, str]:
    """
    Get Compose version information.
    
    Returns:
    - Version information dictionary
    """

Container Operations

Execute commands and perform operations on service containers.

def exec(
    service: str,
    command: List[str],
    *,
    detach: bool = False,
    interactive: bool = False,
    tty: bool = False,
    index: int = 1,
    user: Optional[str] = None,
    workdir: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
    privileged: bool = False
) -> str:
    """
    Execute command in running service container.
    
    Parameters:
    - service: Service name
    - command: Command to execute
    - detach: Run command in background
    - interactive: Keep STDIN open
    - tty: Allocate pseudo-TTY
    - index: Container index if service has multiple replicas
    - user: User to run command as
    - workdir: Working directory
    - env: Environment variables
    - privileged: Run with extended privileges
    
    Returns:
    - Command output (if not detached)
    """

def run(
    service: str,
    command: Optional[List[str]] = None,
    *,
    detach: bool = False,
    name: Optional[str] = None,
    entrypoint: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
    labels: Optional[Dict[str, str]] = None,
    user: Optional[str] = None,
    workdir: Optional[str] = None,
    ports: Optional[Dict[str, str]] = None,
    volumes: Optional[List[str]] = None,
    rm: bool = False,
    no_deps: bool = False,
    service_ports: bool = False,
    use_aliases: bool = False
) -> Union[str, Container]:
    """
    Run one-time commands for services.
    
    Parameters:
    - service: Service name
    - command: Command to run
    - detach: Run in background
    - name: Container name
    - entrypoint: Override entrypoint
    - env: Environment variables
    - labels: Container labels
    - user: User to run as
    - workdir: Working directory
    - ports: Port mappings
    - volumes: Volume mounts
    - rm: Remove container when done
    - no_deps: Don't start linked services
    - service_ports: Use service ports
    - use_aliases: Use service network aliases
    
    Returns:
    - Container object if detach=True, output string otherwise
    """

Image and Volume Operations

Manage images and data associated with Compose services.

def pull(
    services: Optional[List[str]] = None,
    *,
    ignore_pull_failures: bool = False,
    parallel: bool = True,
    quiet: bool = False,
    include_deps: bool = True
) -> None:
    """
    Pull service images.
    
    Parameters:
    - services: Specific services to pull
    - ignore_pull_failures: Continue with other services on failure
    - parallel: Pull images in parallel
    - quiet: Don't print progress
    - include_deps: Pull images for dependencies
    """

def push(
    services: Optional[List[str]] = None,
    *,
    ignore_push_failures: bool = False
) -> None:
    """
    Push service images to registry.
    
    Parameters:
    - services: Specific services to push
    - ignore_push_failures: Continue with other services on failure
    """

def images(
    services: Optional[List[str]] = None,
    *,
    quiet: bool = False
) -> List[Image]:
    """
    List images used by services.
    
    Parameters:
    - services: Specific services to list images for
    - quiet: Only show image IDs
    
    Returns:
    - List of Image objects
    """

Cleanup Operations

Remove containers, networks, and other resources.

def rm(
    services: Optional[List[str]] = None,
    *,
    stop: bool = False,
    force: bool = False,
    volumes: bool = False
) -> None:
    """
    Remove stopped service containers.
    
    Parameters:
    - services: Specific services to remove containers for
    - stop: Stop containers before removing
    - force: Force removal of running containers
    - volumes: Remove associated volumes
    """

def create(
    services: Optional[List[str]] = None,
    *,
    build: bool = False,
    no_build: bool = False,
    pull: Optional[str] = None,
    force_recreate: bool = False,
    no_recreate: bool = False
) -> None:
    """
    Create services without starting them.
    
    Parameters:
    - services: Specific services to create
    - build: Build images before creating
    - no_build: Don't build missing images
    - pull: Pull policy (always, missing, never)
    - force_recreate: Recreate containers even if unchanged
    - no_recreate: Don't recreate existing containers
    """

Usage Examples

Basic Compose Operations

from python_on_whales import docker

# Start all services
docker.compose.up(detach=True)

# View service status
containers = docker.compose.ps()
for container in containers:
    print(f"Service: {container.name} - Status: {container.status}")

# View logs
logs = docker.compose.logs(services=["web"], tail=50)
print(logs)

# Scale a service
docker.compose.up(scale={"web": 3})

# Stop and remove everything
docker.compose.down(volumes=True)

Development Workflow

# Build and start with live reload
docker.compose.up(build=True, detach=True)

# Execute commands in service containers
result = docker.compose.exec(
    "web",
    ["python", "manage.py", "migrate"],
    interactive=True,
    tty=True
)

# View configuration
config = docker.compose.config()
print(config)

# Restart specific service
docker.compose.restart(services=["web"])

Types

class ComposeProject:
    name: str
    services: List[str]
    config_files: List[str]
    
class ComposeService:
    name: str
    image: str
    ports: List[str]
    volumes: List[str]
    environment: Dict[str, str]
    depends_on: List[str]
    
class ComposeConfig:
    version: str
    services: Dict[str, ComposeService]
    networks: Dict[str, Dict[str, Any]]
    volumes: Dict[str, Dict[str, Any]]

Install with Tessl CLI

npx tessl i tessl/pypi-python-on-whales