tessl/pypi-python-on-whales

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

—

Pending

Overview

Eval results

Files

Volume Management

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

Docker volume creation, management, and data persistence operations. Volumes provide persistent data storage that survives container lifecycle changes and can be shared between containers.

Capabilities

Volume Creation and Configuration

Create volumes with specific drivers and configuration options.

def create(
    name: Optional[str] = None,
    *,
    driver: Optional[str] = None,
    driver_options: Optional[Dict[str, str]] = None,
    labels: Optional[Dict[str, str]] = None
) -> Volume:
    """
    Create a new volume.
    
    Parameters:
    - name: Volume name (auto-generated if not provided)
    - driver: Volume driver (local, nfs, etc.)
    - driver_options: Driver-specific options
    - labels: Volume labels
    
    Returns:
    - Volume object
    """

Volume Listing and Inspection

List and inspect volumes with filtering and detailed information retrieval.

def list(
    filters: Optional[Dict[str, str]] = None,
    *,
    quiet: bool = False
) -> List[Volume]:
    """
    List volumes.
    
    Parameters:
    - filters: Filters to apply (dangling, driver, label, name)
    - quiet: Only show volume names
    
    Returns:
    - List of Volume objects
    """

def inspect(volume: str) -> Volume:
    """
    Get detailed information about a volume.
    
    Parameters:
    - volume: Volume name
    
    Returns:
    - Volume object with full details
    """

Volume Cleanup

Remove volumes and clean up unused volumes.

def remove(
    volumes: Union[str, List[str]],
    *,
    force: bool = False
) -> None:
    """
    Remove volumes.
    
    Parameters:
    - volumes: Volume name(s)
    - force: Force removal of volume
    """

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

Usage Examples

Basic Volume Operations

from python_on_whales import docker

# Create a named volume
volume = docker.volume.create("my-data-volume")
print(f"Created volume: {volume.name}")

# List all volumes
volumes = docker.volume.list()
for vol in volumes:
    print(f"Volume: {vol.name} - Driver: {vol.driver}")

# Use volume in container
container = docker.run(
    "alpine:latest",
    ["sh", "-c", "echo 'Hello' > /data/test.txt && cat /data/test.txt"],
    volumes=["my-data-volume:/data"],
    remove=True
)
print(container)

# Remove volume
docker.volume.remove("my-data-volume")

Advanced Volume Configuration

# Create volume with driver options
nfs_volume = docker.volume.create(
    "nfs-storage",
    driver="local",
    driver_options={
        "type": "nfs",
        "o": "addr=192.168.1.100,rw",
        "device": ":/path/to/share"
    },
    labels={"environment": "production"}
)

# Create tmpfs volume
tmpfs_volume = docker.volume.create(
    "temp-data",
    driver="local",
    driver_options={
        "type": "tmpfs",
        "tmpfs-size": "1G"
    }
)

# Filter volumes by label
production_volumes = docker.volume.list(
    filters={"label": "environment=production"}
)

# Clean up unused volumes
prune_result = docker.volume.prune()
print(f"Removed {len(prune_result.get('VolumesDeleted', []))} volumes")

Volume Backup and Restore

# Backup volume data
backup_container = docker.run(
    "alpine:latest",
    ["tar", "czf", "/backup/data.tar.gz", "-C", "/data", "."],
    volumes=[
        "source-volume:/data:ro",
        "/host/backup:/backup"
    ],
    remove=True
)

# Restore volume data
restore_container = docker.run(
    "alpine:latest", 
    ["tar", "xzf", "/backup/data.tar.gz", "-C", "/data"],
    volumes=[
        "target-volume:/data",
        "/host/backup:/backup:ro"
    ],
    remove=True
)

Types

class Volume:
    name: str
    driver: str
    mountpoint: str
    created: str
    scope: str
    labels: Dict[str, str]
    options: Dict[str, str]
    
    def remove(self, force: bool = False) -> None: ...
    def reload(self) -> None: ...

Install with Tessl CLI

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