tessl/pypi-python-on-whales

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

—

Pending

Overview

Eval results

Files

Build Operations

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

Advanced build operations using Docker Buildx for multi-platform builds and BuildKit features. Buildx extends Docker's native build capabilities with enhanced functionality for complex build scenarios.

Capabilities

Builder Management

Create and manage build instances with different drivers and configurations.

def create(
    name: str,
    *,
    driver: Optional[str] = None,
    driver_options: Optional[Dict[str, str]] = None,
    platforms: Optional[List[str]] = None,
    config_file: Optional[str] = None,
    use: bool = False,
    append: bool = False,
    leave: bool = False
) -> Builder:
    """
    Create a new builder instance.
    
    Parameters:
    - name: Builder name
    - driver: Builder driver (docker-container, kubernetes, remote)
    - driver_options: Driver-specific options
    - platforms: Target platforms
    - config_file: BuildKit configuration file
    - use: Set as current builder
    - append: Append node to existing builder
    - leave: Remove current node before adding
    
    Returns:
    - Builder object
    """

def list() -> List[Builder]:
    """
    List available builder instances.
    
    Returns:
    - List of Builder objects
    """

def inspect(name: Optional[str] = None) -> Builder:
    """
    Get detailed information about a builder.
    
    Parameters:
    - name: Builder name (current builder if not specified)
    
    Returns:
    - Builder object with full details
    """

def use(name: str) -> None:
    """
    Set current builder instance.
    
    Parameters:
    - name: Builder name to use
    """

def remove(builders: Union[str, List[str]]) -> None:
    """
    Remove builder instances.
    
    Parameters:
    - builders: Builder name(s) to remove
    """

def stop(builders: Union[str, List[str]]) -> None:
    """
    Stop builder instances.
    
    Parameters:
    - builders: Builder name(s) to stop
    """

Advanced Building

Build images with multi-platform support and advanced BuildKit features.

def build(
    context_path: str,
    *,
    tags: Optional[List[str]] = None,
    builder: Optional[str] = None,
    build_args: Optional[Dict[str, str]] = None,
    cache_from: Optional[List[str]] = None,
    cache_to: Optional[List[str]] = None,
    file: Optional[str] = None,
    labels: Optional[Dict[str, str]] = None,
    load: bool = False,
    platforms: Optional[List[str]] = None,
    progress: str = "auto",
    pull: bool = False,
    push: bool = False,
    secrets: Optional[List[str]] = None,
    ssh: Optional[List[str]] = None,
    target: Optional[str] = None,
    ulimit: Optional[List[str]] = None,
    outputs: Optional[List[str]] = None,
    no_cache: bool = False,
    no_cache_filter: Optional[List[str]] = None,
    allow: Optional[List[str]] = None,
    attests: Optional[List[str]] = None,
    build_contexts: Optional[Dict[str, str]] = None,
    network: Optional[str] = None,
    quiet: bool = False,
    shm_size: Optional[str] = None
) -> Optional[Image]:
    """
    Build image using buildx.
    
    Parameters:
    - context_path: Build context directory
    - tags: Image tags to apply
    - builder: Builder instance to use
    - build_args: Build-time variables
    - cache_from: Cache import locations
    - cache_to: Cache export locations
    - file: Dockerfile path
    - labels: Image labels
    - load: Load image to docker daemon
    - platforms: Target platforms (linux/amd64, linux/arm64, etc.)
    - progress: Progress output type (auto, plain, tty)
    - pull: Always pull base images
    - push: Push image after building
    - secrets: Secrets to expose to build
    - ssh: SSH agent sockets
    - target: Target build stage
    - ulimit: Ulimit settings
    - outputs: Output destinations and formats
    - no_cache: Don't use cache
    - no_cache_filter: Ignore cache for specified stages
    - allow: Allow extra privileged entitlements
    - attests: Attestation options
    - build_contexts: Additional build contexts
    - network: Network mode during build
    - quiet: Suppress build output
    - shm_size: Size of /dev/shm
    
    Returns:
    - Image object (if load=True), None otherwise
    """

Build Configuration and Recipes

Use bake files for complex multi-target builds.

def bake(
    targets: Optional[List[str]] = None,
    *,
    file: Optional[List[str]] = None,
    load: bool = False,
    print_: bool = False,
    progress: str = "auto",
    pull: bool = False,
    push: bool = False,
    set_: Optional[List[str]] = None,
    builder: Optional[str] = None,
    no_cache: bool = False,
    call: Optional[str] = None
) -> None:
    """
    Build from bake file.
    
    Parameters:
    - targets: Build targets to execute
    - file: Bake file paths
    - load: Load images to docker daemon
    - print_: Print bake file in JSON format
    - progress: Progress output type
    - pull: Always pull base images
    - push: Push images after building
    - set_: Override build arguments
    - builder: Builder instance to use
    - no_cache: Don't use cache
    - call: Call build method (build, check, outline, targets)
    """

Build Utilities

Manage build cache and inspect build history.

def disk_usage() -> Dict[str, Any]:
    """
    Show buildx disk usage.
    
    Returns:
    - Disk usage information including build cache
    """

def prune(
    *,
    all: bool = False,
    filters: Optional[Dict[str, str]] = None,
    force: bool = False,
    keep_storage: Optional[str] = None
) -> Dict[str, Any]:
    """
    Remove build cache.
    
    Parameters:
    - all: Remove all cache, not just dangling
    - filters: Filters to apply
    - force: Don't prompt for confirmation
    - keep_storage: Amount of cache to keep
    
    Returns:
    - Information about removed cache
    """

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

def is_installed() -> bool:
    """
    Check if buildx is available.
    
    Returns:
    - True if buildx is installed and available
    """

Image Tools

Advanced image manipulation and multi-platform operations.

class ImagetoolsCLI:
    def create(
        self,
        tags: List[str],
        *,
        sources: Optional[List[str]] = None,
        dry_run: bool = False,
        append: bool = False,
        progress: str = "auto"
    ) -> None:
        """
        Create multi-platform manifest.
        
        Parameters:
        - tags: Target image tags
        - sources: Source images to combine
        - dry_run: Show what would be created
        - append: Append to existing manifest
        - progress: Progress output type
        """
    
    def inspect(
        self,
        image: str,
        *,
        raw: bool = False,
        format: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        Inspect multi-platform image.
        
        Parameters:
        - image: Image name or reference
        - raw: Show original manifest
        - format: Output format (json, template)
        
        Returns:
        - Image inspection information
        """

Usage Examples

Multi-Platform Building

from python_on_whales import docker

# Create a builder for multi-platform builds
builder = docker.buildx.create(
    "multiplatform-builder",
    driver="docker-container",
    platforms=["linux/amd64", "linux/arm64"]
)
docker.buildx.use("multiplatform-builder")

# Build for multiple platforms
docker.buildx.build(
    ".",
    tags=["myapp:latest"],
    platforms=["linux/amd64", "linux/arm64"],
    push=True,
    cache_from=["type=registry,ref=myapp:cache"],
    cache_to=["type=registry,ref=myapp:cache,mode=max"]
)

Advanced Build Features

# Build with secrets and SSH forwarding
docker.buildx.build(
    ".",
    tags=["myapp:secure"],
    secrets=["id=mysecret,src=/path/to/secret"],
    ssh=["default=/path/to/ssh/key"],
    build_args={"BUILD_ENV": "production"},
    target="production"
)

# Build with custom outputs
docker.buildx.build(
    ".",
    tags=["myapp:local"],
    outputs=["type=local,dest=./output"],
    platforms=["linux/amd64"]
)

# Build using bake file
docker.buildx.bake(
    targets=["web", "api"],
    file=["docker-bake.json"],
    push=True,
    set_=["web.args.VERSION=v1.2.3"]
)

Cache Management

# Check disk usage
usage = docker.buildx.disk_usage()
print(f"Total cache size: {usage['Total']}")

# Clean up build cache
prune_result = docker.buildx.prune(
    all=True,
    keep_storage="10GB"
)
print(f"Freed: {prune_result['SpaceReclaimed']}")

Types

class Builder:
    name: str
    driver: str
    last_activity: Optional[str]
    dynamic: bool
    nodes: List[Dict[str, Any]]
    
    def remove(self) -> None: ...
    def use(self) -> None: ...
    def stop(self) -> None: ...

class BuilderNode:
    name: str
    endpoint: str
    driver_options: Dict[str, str]
    status: str
    flags: List[str]
    platforms: List[str]

class DiskUsageResult:
    build_cache: List[Dict[str, Any]]
    total_size: int
    reclaimable_size: int

Install with Tessl CLI

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