tessl/pypi-python-on-whales

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

—

Pending

Overview

Eval results

Files

Pod Management

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

Note: This is Podman-specific functionality, not available in Docker.

Podman pod management for grouping containers with shared namespaces, networking, and storage. Pods provide a way to run multiple containers together as a cohesive unit, similar to Kubernetes pods.

Capabilities

Pod Creation

Create pods with shared namespaces and networking configuration.

def create(
    name: Optional[str] = None,
    *,
    add_hosts: Optional[List[str]] = None,
    cgroup_parent: Optional[str] = None,
    cpu_shares: Optional[int] = None,
    cpus: Optional[float] = None,
    cpuset_cpus: Optional[str] = None,
    dns: Optional[List[str]] = None,
    dns_options: Optional[List[str]] = None,
    dns_search: Optional[List[str]] = None,
    gidmap: Optional[List[str]] = None,
    hostname: Optional[str] = None,
    infra: bool = True,
    infra_command: Optional[str] = None,
    infra_image: Optional[str] = None,
    ip: Optional[str] = None,
    labels: Optional[Dict[str, str]] = None,
    mac_address: Optional[str] = None,
    memory: Optional[str] = None,
    network: Optional[str] = None,
    no_hosts: bool = False,
    pid: Optional[str] = None,
    pod_id_file: Optional[str] = None,
    publish: Optional[List[str]] = None,
    replace: bool = False,
    share: Optional[str] = None,
    subgidname: Optional[str] = None,
    subuidname: Optional[str] = None,
    uidmap: Optional[List[str]] = None,
    userns: Optional[str] = None,
    uts: Optional[str] = None,
    volume: Optional[List[str]] = None
) -> Pod:
    """
    Create a new pod with extensive configuration options.
    
    Parameters:
    - name: Pod name (auto-generated if not provided)
    - add_hosts: Add host-to-IP mappings
    - cgroup_parent: Parent cgroup for the pod
    - cpu_shares: CPU shares (relative weight)
    - cpus: Number of CPUs  
    - cpuset_cpus: CPU set for execution
    - dns: DNS servers
    - dns_options: DNS options
    - dns_search: DNS search domains
    - gidmap: GID map for user namespace
    - hostname: Pod hostname
    - infra: Create infra container (default: True)
    - infra_command: Command for infra container
    - infra_image: Image for infra container
    - ip: IP address for pod
    - labels: Metadata labels
    - mac_address: MAC address
    - memory: Memory limit
    - network: Network mode
    - no_hosts: Don't create /etc/hosts
    - pid: PID namespace mode
    - pod_id_file: Write pod ID to file
    - publish: Port mappings
    - replace: Replace existing pod with same name
    - share: Shared namespaces
    - subgidname: Name of subordinate GID range
    - subuidname: Name of subordinate UID range  
    - uidmap: UID map for user namespace
    - userns: User namespace mode
    - uts: UTS namespace mode
    - volume: Volume mounts
    
    Returns:
    Pod object
    """

Pod Lifecycle Management

Start, stop, pause, and restart pods.

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

def stop(
    x: Union[str, List[str]], 
    time: Optional[int] = None
) -> None:
    """
    Stop one or more pods.
    
    Parameters:
    - x: Pod name(s) or ID(s)
    - time: Timeout in seconds before force kill
    """

def restart(x: Union[str, List[str]]) -> None:
    """
    Restart one or more pods.
    
    Parameters:
    - x: Pod name(s) or ID(s)
    """

def pause(x: Union[str, List[str]]) -> None:
    """
    Pause one or more pods.
    
    Parameters:
    - x: Pod name(s) or ID(s)
    """

def unpause(x: Union[str, List[str]]) -> None:
    """
    Unpause one or more pods.
    
    Parameters:
    - x: Pod name(s) or ID(s)
    """

def kill(
    x: Union[str, List[str]], 
    signal: Optional[str] = None
) -> None:
    """
    Kill one or more pods.
    
    Parameters:
    - x: Pod name(s) or ID(s)
    - signal: Signal to send (default: SIGKILL)
    """

Pod Information and Monitoring

Inspect pods, check existence, and view logs.

def inspect(x: Union[str, List[str]]) -> Union[Pod, List[Pod]]:
    """
    Inspect one or more pods.
    
    Parameters:
    - x: Pod name(s) or ID(s)
    
    Returns:
    Pod object(s) with detailed information
    """

def exists(pod: Union[str, Pod]) -> bool:
    """
    Check if a pod exists.
    
    Parameters:
    - pod: Pod name/ID or Pod object
    
    Returns:
    True if pod exists, False otherwise
    """

def list(filters: Sequence[str] = ()) -> List[Pod]:
    """
    List pods with optional filters.
    
    Parameters:
    - filters: Filter conditions
    
    Returns:
    List of Pod objects
    """

def logs(
    pod: Union[str, Pod],
    container: Optional[str] = None,
    *,
    names: bool = False,
    since: Optional[str] = None,
    tail: Optional[int] = None,
    timestamps: bool = False,
    until: Optional[str] = None,
    follow: bool = False,
    stream: bool = False
) -> Union[str, Iterable[Tuple[str, bytes]]]:
    """
    Get pod or container logs.
    
    Parameters:
    - pod: Pod name/ID or Pod object
    - container: Specific container in pod
    - names: Show container names in output
    - since: Show logs since timestamp
    - tail: Number of lines from end
    - timestamps: Show timestamps
    - until: Show logs until timestamp
    - follow: Follow log output
    - stream: Return streaming iterator
    
    Returns:
    Log output as string or streaming iterator
    """

Pod Cleanup

Remove pods and prune unused pods.

def remove(
    x: Union[str, List[str]], 
    force: bool = False,
    ignore: bool = False,
    time: Optional[int] = None
) -> None:
    """
    Remove one or more pods.
    
    Parameters:
    - x: Pod name(s) or ID(s)
    - force: Force removal
    - ignore: Ignore errors
    - time: Timeout before force kill
    """

def prune() -> None:
    """
    Remove all non-running pods.
    """

Usage Examples:

from python_on_whales import docker  # Note: This requires Podman backend

# Create a pod with shared networking
pod = docker.pod.create(
    "web-app-pod",
    hostname="web-server",
    publish=["8080:80", "8443:443"],
    labels={"app": "web", "environment": "production"}
)

# Start the pod
docker.pod.start("web-app-pod")

# Add containers to the pod (using regular container create with --pod option)
web_container = docker.create(
    "nginx:alpine",
    pod=pod.name,
    name="web-server"
)

app_container = docker.create(
    "python:3.9",
    ["python", "app.py"],
    pod=pod.name,
    name="app-server"
)

# Get pod logs
logs = docker.pod.logs("web-app-pod", follow=True, stream=True)
for source, line in logs:
    print(f"{source}: {line.decode()}")

# Stop and remove pod
docker.pod.stop("web-app-pod")
docker.pod.remove("web-app-pod")

Types

class Pod:
    id: str
    name: str
    created: str
    create_command: List[str]
    exit_policy: str
    state: str
    hostname: str
    labels: Dict[str, str]
    create_cgroup: bool
    cgroup_parent: str
    cgroup_path: str
    create_infra: bool  
    infra_container_id: str
    infra_config: Dict[str, Any]
    shared_namespaces: List[str]
    num_containers: int
    containers: List[Dict[str, Any]]
    
    def exists(self) -> bool:
        """Check if this pod exists."""
    
    def kill(self, signal: Optional[str] = None) -> None:
        """Kill this pod."""
    
    def logs(
        self,
        container: Optional[str] = None,
        names: bool = False,
        since: Optional[str] = None,
        tail: Optional[int] = None,
        timestamps: bool = False,
        until: Optional[str] = None,
        follow: bool = False,
        stream: bool = False
    ) -> Union[str, Iterable[Tuple[str, bytes]]]:
        """Get logs for this pod."""
    
    def pause(self) -> None:
        """Pause this pod."""
    
    def unpause(self) -> None:
        """Unpause this pod."""
    
    def restart(self) -> None:
        """Restart this pod."""
    
    def remove(
        self, 
        force: bool = False, 
        time: Optional[int] = None
    ) -> None:
        """Remove this pod."""
    
    def start(self) -> None:
        """Start this pod."""
    
    def stop(self, time: Optional[int] = None) -> None:
        """Stop this pod."""

Install with Tessl CLI

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