tessl/pypi-python-on-whales

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

—

Pending

Overview

Eval results

Files

Plugin Management

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

Docker plugin management for extending Docker functionality with third-party plugins. Plugins provide additional capabilities like storage drivers, network drivers, and authorization mechanisms that integrate seamlessly with Docker.

Capabilities

Plugin Installation

Install plugins from Docker Hub or custom registries with automatic permission granting.

def install(
    plugin_name: str,
    configuration: Optional[List[str]] = None,
    alias: Optional[str] = None,
    disable: bool = False,
    disable_content_trust: bool = True
) -> Plugin:
    """
    Install a plugin with automatic permission granting.
    
    Parameters:
    - plugin_name: Plugin name (e.g., "store/sumologic/docker-logging-driver")
    - configuration: Configuration options as key=value pairs
    - alias: Local alias for the plugin
    - disable: Install but leave disabled
    - disable_content_trust: Skip content trust verification
    
    Returns:
    Plugin object
    """

Plugin Creation

Create plugins from rootfs directories.

def create(
    plugin_name: str,
    plugin_data_directory: str,
    compress: bool = False
) -> Plugin:
    """
    Create a plugin from a rootfs directory.
    
    Parameters:
    - plugin_name: Name for the new plugin
    - plugin_data_directory: Path to plugin rootfs directory
    - compress: Compress plugin data
    
    Returns:
    Plugin object
    """

Plugin State Management

Enable and disable plugins dynamically.

def enable(
    plugin: Union[str, Plugin],
    timeout: Optional[int] = None
) -> None:
    """
    Enable a plugin.
    
    Parameters:
    - plugin: Plugin name/ID or Plugin object
    - timeout: Timeout in seconds
    """

def disable(
    plugin: Union[str, Plugin],
    force: bool = False
) -> None:
    """
    Disable a plugin.
    
    Parameters:
    - plugin: Plugin name/ID or Plugin object  
    - force: Force disable even if in use
    """

Plugin Configuration

Update plugin settings after installation.

def set(
    plugin: Union[str, Plugin],
    configuration: List[str]
) -> None:
    """
    Change plugin configuration settings.
    
    Parameters:
    - plugin: Plugin name/ID or Plugin object
    - configuration: Configuration options as key=value pairs
    """

Plugin Inspection

Inspect plugin details including configuration and capabilities.

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

Plugin Listing

List all installed plugins.

def list() -> List[Plugin]:
    """
    List all installed plugins.
    
    Returns:
    List of Plugin objects
    """

Plugin Registry Operations

Push plugins to registries and upgrade installed plugins.

def push(
    plugin: Union[str, Plugin],
    disable_content_trust: bool = True
) -> None:
    """
    Push plugin to registry.
    
    Parameters:
    - plugin: Plugin name/ID or Plugin object
    - disable_content_trust: Skip content trust verification
    """

def upgrade(
    plugin: Union[str, Plugin],
    remote: Optional[str] = None,
    disable_content_trust: bool = True,
    skip_remote_check: bool = False
) -> None:
    """
    Upgrade a plugin.
    
    Parameters:
    - plugin: Plugin name/ID or Plugin object
    - remote: Remote plugin reference to upgrade to
    - disable_content_trust: Skip content trust verification
    - skip_remote_check: Skip remote existence check
    """

Plugin Removal

Remove plugins from the system.

def remove(
    x: Union[str, List[str]],
    force: bool = False
) -> None:
    """
    Remove one or more plugins.
    
    Parameters:
    - x: Plugin name(s) or ID(s) to remove
    - force: Force removal even if plugin is enabled
    """

Usage Examples:

from python_on_whales import docker

# Install logging plugin
plugin = docker.plugin.install(
    "store/sumologic/docker-logging-driver:1.0.0",
    alias="sumologic"
)

# Configure plugin
docker.plugin.set("sumologic", ["SUMO_URL=https://collectors.sumologic.com"])

# Enable plugin
docker.plugin.enable("sumologic")

# List all plugins
plugins = docker.plugin.list()
for plugin in plugins:
    print(f"Plugin: {plugin.name} - Enabled: {plugin.enabled}")

# Disable and remove plugin
docker.plugin.disable("sumologic")
docker.plugin.remove("sumologic")

Types

class Plugin:
    id: str
    name: str
    enabled: bool
    settings: PluginSettings
    plugin_reference: str
    config: PluginConfig
    
    def disable(self, force: bool = False) -> None:
        """Disable this plugin."""
    
    def enable(self, timeout: Optional[int] = None) -> None:
        """Enable this plugin."""
    
    def push(self, disable_content_trust: bool = True) -> None:
        """Push this plugin to registry."""
    
    def remove(self, force: bool = False) -> None:
        """Remove this plugin."""
    
    def set(self, configuration: List[str]) -> None:
        """Update this plugin's configuration."""
    
    def upgrade(
        self,
        remote: Optional[str] = None,
        disable_content_trust: bool = True,
        skip_remote_check: bool = False
    ) -> None:
        """Upgrade this plugin."""

class PluginSettings:
    mounts: List[Dict[str, Any]]
    env: List[str]
    args: List[str]
    devices: List[Dict[str, Any]]

class PluginConfig:
    docker_version: str
    description: str
    documentation: str
    interface: Dict[str, Any]
    entrypoint: List[str]
    work_dir: str
    user: Dict[str, Any]
    network: Dict[str, str]
    linux: Dict[str, Any]
    propagated_mount: str
    ipc_host: bool
    pid_host: bool
    mounts: List[Dict[str, Any]]
    env: List[Dict[str, str]]
    args: Dict[str, Any]

Install with Tessl CLI

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