tessl/pypi-python-on-whales

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

—

Pending

Overview

Eval results

Files

Container Operations

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

Comprehensive container lifecycle management including creation, execution, monitoring, and cleanup operations. Containers represent running instances of Docker images with isolated processes, filesystems, and networking.

Capabilities

Container Creation and Running

Create and run containers from images with extensive configuration options for networking, volumes, environment variables, and resource constraints.

def run(
    image: str,
    command: Optional[Sequence[str]] = (),
    *,
    add_hosts: Optional[List[Tuple[str, str]]] = None,
    blkio_weight: Optional[int] = None,
    cap_add: Optional[List[str]] = None,
    cap_drop: Optional[List[str]] = None,
    cgroup_parent: Optional[str] = None,
    cgroupns: Optional[str] = None,
    cidfile: Optional[str] = None,
    cpu_period: Optional[int] = None,
    cpu_quota: Optional[int] = None,
    cpu_shares: Optional[int] = None,
    cpus: Optional[float] = None,
    cpuset_cpus: Optional[List[int]] = None,
    cpuset_mems: Optional[List[int]] = None,
    detach: bool = False,
    devices: Optional[List[str]] = None,
    dns: Optional[List[str]] = None,
    dns_options: Optional[List[str]] = None,
    dns_search: Optional[List[str]] = None,
    domainname: Optional[str] = None,
    entrypoint: Optional[str] = None,
    envs: Optional[Dict[str, str]] = None,
    env_files: Optional[List[str]] = None,
    env_host: bool = False,
    expose: Optional[List[int]] = None,
    gpus: Optional[Union[int, str]] = None,
    groups_add: Optional[List[str]] = None,
    healthcheck: bool = True,
    health_cmd: Optional[str] = None,
    health_interval: Optional[Union[int, str]] = None,
    health_retries: Optional[int] = None,
    health_start_period: Optional[Union[int, str]] = None,
    health_timeout: Optional[Union[int, str]] = None,
    hostname: Optional[str] = None,
    init: bool = False,
    interactive: bool = False,
    ip: Optional[str] = None,
    ip6: Optional[str] = None,
    ipc: Optional[str] = None,
    isolation: Optional[str] = None,
    kernel_memory: Optional[Union[int, str]] = None,
    labels: Optional[Dict[str, str]] = None,
    label_files: Optional[List[str]] = None,
    link: Optional[List[str]] = None,
    link_local_ip: Optional[List[str]] = None,
    log_driver: Optional[str] = None,
    log_options: Optional[List[str]] = None,
    mac_address: Optional[str] = None,
    memory: Optional[Union[int, str]] = None,
    memory_reservation: Optional[Union[int, str]] = None,
    memory_swap: Optional[Union[int, str]] = None,
    memory_swappiness: Optional[int] = None,
    mounts: Optional[List[str]] = None,
    name: Optional[str] = None,
    networks: Optional[List[str]] = None,
    network_aliases: Optional[List[str]] = None,
    oom_kill: bool = True,
    oom_score_adj: Optional[int] = None,
    pid: Optional[str] = None,
    pids_limit: Optional[int] = None,
    platform: Optional[str] = None,
    pod: Optional[str] = None,
    preserve_fds: Optional[int] = None,
    privileged: bool = False,
    publish: Optional[List[str]] = None,
    publish_all: bool = False,
    pull: str = "missing",
    read_only: bool = False,
    restart: Optional[str] = None,
    remove: bool = False,
    runtime: Optional[str] = None,
    security_options: Optional[List[str]] = None,
    shm_size: Optional[Union[int, str]] = None,
    sig_proxy: bool = True,
    stop_signal: Optional[Union[int, str]] = None,
    stop_timeout: Optional[int] = None,
    storage_options: Optional[List[str]] = None,
    stream: bool = False,
    sysctl: Optional[Dict[str, str]] = None,
    systemd: Optional[Union[bool, str]] = None,
    tmpfs: Optional[List[str]] = None,
    tty: bool = False,
    tz: Optional[str] = None,
    ulimit: Optional[List[str]] = None,
    user: Optional[str] = None,
    userns: Optional[str] = None,
    uts: Optional[str] = None,
    volumes: Optional[List[str]] = None,
    volume_driver: Optional[str] = None,
    volumes_from: Optional[List[str]] = None,
    workdir: Optional[str] = None
) -> Union[str, Container]:
    """
    Run a container from an image with comprehensive configuration options.
    
    Parameters:
    - image: Docker image name or ID
    - command: Command to run in container
    - add_hosts: Host to IP mappings
    - blkio_weight: Block IO weight (10-1000)
    - cap_add: Linux capabilities to add
    - cap_drop: Linux capabilities to drop
    - cgroup_parent: Parent cgroup for container
    - cgroupns: Cgroup namespace mode
    - cidfile: Write container ID to file
    - cpu_period: CPU CFS period limit
    - cpu_quota: CPU CFS quota limit
    - cpu_shares: CPU shares (relative weight)
    - cpus: Number of CPUs
    - cpuset_cpus: CPUs to use
    - cpuset_mems: Memory nodes to use
    - detach: Run container in background
    - devices: Device mappings
    - dns: DNS servers
    - dns_options: DNS options
    - dns_search: DNS search domains
    - domainname: Container NIS domain name
    - entrypoint: Override image entrypoint
    - envs: Environment variables as dict
    - env_files: Environment files to load
    - env_host: Use host environment variables
    - expose: Expose ports without publishing
    - gpus: GPU devices to use
    - groups_add: Additional groups for user
    - healthcheck: Enable/disable healthcheck
    - health_cmd: Health check command
    - health_interval: Health check interval
    - health_retries: Health check retries
    - health_start_period: Health check start period
    - health_timeout: Health check timeout
    - hostname: Container hostname
    - init: Run init inside container
    - interactive: Keep STDIN open
    - ip: IPv4 address
    - ip6: IPv6 address
    - ipc: IPC mode
    - isolation: Container isolation technology
    - kernel_memory: Kernel memory limit
    - labels: Container labels
    - label_files: Label files to read
    - link: Link to containers (deprecated)
    - link_local_ip: Container IPv4/IPv6 link-local addresses
    - log_driver: Logging driver
    - log_options: Log driver options
    - mac_address: Container MAC address
    - memory: Memory limit
    - memory_reservation: Memory soft limit
    - memory_swap: Swap limit
    - memory_swappiness: Tune container memory swappiness
    - mounts: Filesystem mounts
    - name: Container name
    - networks: Networks to connect to
    - network_aliases: Network-scoped aliases
    - oom_kill: Enable OOM killer
    - oom_score_adj: OOM score adjustment
    - pid: PID namespace mode
    - pids_limit: PIDs limit
    - platform: Target platform
    - pod: Pod to join (Podman)
    - preserve_fds: Preserve additional file descriptors
    - privileged: Run with extended privileges
    - publish: Port mappings
    - publish_all: Publish all exposed ports
    - pull: Pull image policy (always, missing, never)
    - read_only: Mount root filesystem as read-only
    - restart: Restart policy
    - remove: Remove container when it exits
    - runtime: Runtime to use
    - security_options: Security options
    - shm_size: Size of /dev/shm
    - sig_proxy: Proxy received signals to process
    - stop_signal: Signal to stop container
    - stop_timeout: Timeout to stop container
    - storage_options: Storage driver options
    - stream: Stream container output
    - sysctl: Sysctl options
    - systemd: Enable systemd mode
    - tmpfs: Tmpfs mounts
    - tty: Allocate pseudo-TTY
    - tz: Timezone
    - ulimit: Ulimit options
    - user: User to run as
    - userns: User namespace mode
    - uts: UTS namespace mode
    - volumes: Volume mounts
    - volume_driver: Volume driver
    - volumes_from: Mount volumes from containers
    - workdir: Working directory
    
    Returns:
    - Container object if detach=True, output string otherwise
    """

def create(
    image: str,
    command: Optional[List[str]] = None,
    **kwargs
) -> Container:
    """
    Create a container without starting it.
    
    Parameters:
    - image: Docker image name or ID
    - command: Command to run in container
    - **kwargs: Same options as run()
    
    Returns:
    - Container object
    """

Container Listing and Inspection

List and inspect containers with filtering and detailed information retrieval.

def ps(
    all: bool = False,
    filters: Optional[Dict[str, str]] = None,
    size: bool = False,
    latest: bool = False,
    quiet: bool = False
) -> List[Container]:
    """
    List containers.
    
    Parameters:
    - all: Show all containers (default shows just running)
    - filters: Filters to apply (name, status, etc.)
    - size: Include container sizes
    - latest: Show only latest created container
    - quiet: Only display container IDs
    
    Returns:
    - List of Container objects
    """

def inspect(container: str) -> Container:
    """
    Get detailed information about a container.
    
    Parameters:
    - container: Container name or ID
    
    Returns:
    - Container object with full details
    """

Container Lifecycle Control

Start, stop, restart, and manage container execution states.

def start(containers: Union[str, List[str]]) -> None:
    """
    Start one or more containers.
    
    Parameters:
    - containers: Container name(s) or ID(s)
    """

def stop(
    containers: Union[str, List[str]],
    timeout: Optional[int] = None
) -> None:
    """
    Stop running containers.
    
    Parameters:
    - containers: Container name(s) or ID(s)
    - timeout: Seconds to wait before force killing
    """

def restart(
    containers: Union[str, List[str]],
    timeout: Optional[int] = None
) -> None:
    """
    Restart containers.
    
    Parameters:
    - containers: Container name(s) or ID(s)
    - timeout: Seconds to wait before force killing
    """

def kill(
    containers: Union[str, List[str]],
    signal: str = "SIGKILL"
) -> None:
    """
    Kill running containers.
    
    Parameters:
    - containers: Container name(s) or ID(s)
    - signal: Signal to send (SIGKILL, SIGTERM, etc.)
    """

def pause(containers: Union[str, List[str]]) -> None:
    """
    Pause containers (suspend all processes).
    
    Parameters:
    - containers: Container name(s) or ID(s)
    """

def unpause(containers: Union[str, List[str]]) -> None:
    """
    Unpause containers.
    
    Parameters:
    - containers: Container name(s) or ID(s)
    """

Container Execution and Interaction

Execute commands in running containers and interact with container processes.

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

def attach(container: str, detach_keys: Optional[str] = None) -> None:
    """
    Attach to running container.
    
    Parameters:
    - container: Container name or ID
    - detach_keys: Key sequence for detaching
    """

Container Logs and Monitoring

Retrieve container logs and monitor container statistics.

def logs(
    container: str,
    *,
    follow: bool = False,
    tail: Optional[int] = None,
    since: Optional[str] = None,
    until: Optional[str] = None,
    timestamps: bool = False,
    details: bool = False
) -> str:
    """
    Get container logs.
    
    Parameters:
    - container: Container name or ID
    - 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
    - details: Show extra log details
    
    Returns:
    - Log output string
    """

def stats(
    containers: Optional[List[str]] = None,
    all: bool = False,
    no_stream: bool = True
) -> Union[List[ContainerStats], Iterator[List[ContainerStats]]]:
    """
    Get container resource usage statistics.
    
    Parameters:
    - containers: Specific containers to monitor
    - all: Include stopped containers
    - no_stream: Return single result instead of stream
    
    Returns:
    - Container statistics (list or iterator)
    """

def top(container: str, ps_options: Optional[str] = None) -> List[Dict[str, str]]:
    """
    Display running processes in container.
    
    Parameters:
    - container: Container name or ID
    - ps_options: ps command options
    
    Returns:
    - List of process information dictionaries
    """

Container File Operations

Copy files between containers and host filesystem.

def copy(
    source: str,
    destination: str,
    *,
    archive: bool = False,
    follow_link: bool = False
) -> None:
    """
    Copy files/folders between container and host.
    
    Parameters:
    - source: Source path (container:path or host path)
    - destination: Destination path (container:path or host path)
    - archive: Preserve tar archive format
    - follow_link: Follow symbolic links in source
    """

Container Management

Rename, update, and remove containers.

def rename(container: str, new_name: str) -> None:
    """
    Rename container.
    
    Parameters:
    - container: Current container name or ID
    - new_name: New container name
    """

def update(
    containers: Union[str, List[str]],
    *,
    cpus: Optional[float] = None,
    memory: Optional[str] = None,
    restart: Optional[str] = None,
    **kwargs
) -> None:
    """
    Update container configuration.
    
    Parameters:
    - containers: Container name(s) or ID(s)
    - cpus: CPU limit
    - memory: Memory limit
    - restart: Restart policy
    """

def remove(
    containers: Union[str, List[str]],
    *,
    force: bool = False,
    volumes: bool = False,
    links: bool = False
) -> None:
    """
    Remove containers.
    
    Parameters:
    - containers: Container name(s) or ID(s)
    - force: Force removal of running containers
    - volumes: Remove associated volumes
    - links: Remove network links
    """

def prune(filters: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
    """
    Remove stopped containers.
    
    Parameters:
    - filters: Filters to apply
    
    Returns:
    - Information about removed containers
    """

Container State Operations

Wait for containers and monitor state changes.

def wait(
    containers: Union[str, List[str]],
    condition: str = "not-running"
) -> List[Dict[str, Any]]:
    """
    Wait for containers to reach specified condition.
    
    Parameters:
    - containers: Container name(s) or ID(s)
    - condition: Condition to wait for (not-running, next-exit, removed)
    
    Returns:
    - List of container exit information
    """

def diff(container: str) -> List[Dict[str, str]]:
    """
    Show changes to container filesystem.
    
    Parameters:
    - container: Container name or ID
    
    Returns:
    - List of filesystem changes
    """

Types

class Container:
    id: str
    name: str
    image: str
    command: str
    created: str
    state: str
    status: str
    ports: Dict[str, Any]
    labels: Dict[str, str]
    mounts: List[Dict[str, Any]]
    network_settings: Dict[str, Any]
    
    def remove(self, force: bool = False, volumes: bool = False) -> None: ...
    def start(self) -> None: ...
    def stop(self, timeout: Optional[int] = None) -> None: ...
    def restart(self, timeout: Optional[int] = None) -> None: ...
    def kill(self, signal: str = "SIGKILL") -> None: ...
    def pause(self) -> None: ...
    def unpause(self) -> None: ...
    def logs(self, follow: bool = False, tail: Optional[int] = None) -> str: ...
    def execute(self, command: List[str], **kwargs) -> str: ...
    def rename(self, new_name: str) -> None: ...
    def update(self, **kwargs) -> None: ...
    def copy_from(self, source_path: str, destination_path: str) -> None: ...
    def copy_to(self, source_path: str, destination_path: str) -> None: ...
    def export(self, output_path: str) -> None: ...
    def commit(self, repository: Optional[str] = None, tag: Optional[str] = None, **kwargs) -> Image: ...
    def diff(self) -> List[Dict[str, str]]: ...
    def stats(self, no_stream: bool = True) -> ContainerStats: ...
    def top(self, ps_options: Optional[str] = None) -> List[Dict[str, str]]: ...
    def wait(self, condition: str = "not-running") -> Dict[str, Any]: ...
    def attach(self, detach_keys: Optional[str] = None) -> None: ...

class ContainerStats:
    container_id: str
    name: str
    cpu_percentage: float
    memory_usage: str
    memory_percentage: float
    network_io: str
    block_io: str
    pids: int

Install with Tessl CLI

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