ptctools 0.1.0__py3-none-any.whl

ptctools/__init__.py

@@ -0,0 +1,3 @@
+"""Portainer Client Tools - CLI for managing Portainer stacks and backups."""
+
+__version__ = "0.1.0"

ptctools/_portainer.py

@@ -0,0 +1,279 @@
+"""
+Common utility functions for Portainer API scripts.
+"""
+
+from __future__ import annotations
+
+import json
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError, URLError
+
+
+def api_request(
+    url: str,
+    api_key: str,
+    method: str = "GET",
+    data: dict | None = None,
+) -> tuple[dict | list | None, int]:
+    """Make an API request to Portainer."""
+    headers = {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+    }
+
+    body = json.dumps(data).encode("utf-8") if data else None
+    req = Request(url, data=body, headers=headers, method=method)
+
+    try:
+        with urlopen(req) as response:
+            response_body = response.read().decode("utf-8")
+            return json.loads(response_body) if response_body else None, response.status
+    except HTTPError as e:
+        response_body = e.read().decode("utf-8")
+        try:
+            return json.loads(response_body), e.code
+        except json.JSONDecodeError:
+            return {"error": response_body}, e.code
+    except URLError as e:
+        return {"error": str(e.reason)}, 0
+
+
+def create_container(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    config: dict,
+) -> str | None:
+    """Create a container and return its ID."""
+    url = f"{portainer_url}/api/endpoints/{endpoint_id}/docker/containers/create"
+    response, status_code = api_request(url, api_key, method="POST", data=config)
+
+    if 200 <= status_code < 300 and response:
+        return response.get("Id")
+    else:
+        print(f"Error creating container (HTTP {status_code}):")
+        print(json.dumps(response, indent=2))
+        return None
+
+
+def pull_image(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    image: str,
+) -> bool:
+    """Pull a Docker image."""
+    from urllib.request import Request, urlopen
+    from urllib.parse import quote
+
+    url = f"{portainer_url}/api/endpoints/{endpoint_id}/docker/images/create?fromImage={quote(image)}"
+    headers = {"X-API-Key": api_key}
+    req = Request(url, data=b"", headers=headers, method="POST")
+
+    try:
+        with urlopen(req) as response:
+            # Read streaming response (Docker sends progress updates)
+            response.read()
+            return response.status == 200
+    except Exception:
+        return False
+
+
+def start_container(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    container_id: str,
+) -> bool:
+    """Start a container."""
+    url = f"{portainer_url}/api/endpoints/{endpoint_id}/docker/containers/{container_id}/start"
+    _, status_code = api_request(url, api_key, method="POST")
+    return 200 <= status_code < 300
+
+
+def wait_container(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    container_id: str,
+) -> int:
+    """Wait for a container to finish and return exit code."""
+    url = f"{portainer_url}/api/endpoints/{endpoint_id}/docker/containers/{container_id}/wait"
+    response, status_code = api_request(url, api_key, method="POST")
+
+    if 200 <= status_code < 300 and response:
+        return response.get("StatusCode", -1)
+    return -1
+
+
+def get_container_logs(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    container_id: str,
+) -> str:
+    """Get container logs."""
+    url = f"{portainer_url}/api/endpoints/{endpoint_id}/docker/containers/{container_id}/logs?stdout=true&stderr=true"
+
+    headers = {"X-API-Key": api_key}
+    req = Request(url, headers=headers, method="GET")
+
+    try:
+        with urlopen(req) as response:
+            # Docker logs have stream headers, strip them
+            raw_logs = response.read()
+            # Simple cleanup - remove Docker stream headers (8 bytes each)
+            logs = ""
+            i = 0
+            while i < len(raw_logs):
+                if i + 8 <= len(raw_logs):
+                    size = int.from_bytes(raw_logs[i + 4 : i + 8], "big")
+                    if i + 8 + size <= len(raw_logs):
+                        logs += raw_logs[i + 8 : i + 8 + size].decode(
+                            "utf-8", errors="replace"
+                        )
+                        i += 8 + size
+                        continue
+                break
+            return logs
+    except Exception as e:
+        return f"Error getting logs: {e}"
+
+
+def remove_container(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    container_id: str,
+) -> bool:
+    """Remove a container."""
+    url = f"{portainer_url}/api/endpoints/{endpoint_id}/docker/containers/{container_id}?force=true"
+    _, status_code = api_request(url, api_key, method="DELETE")
+    return 200 <= status_code < 300
+
+
+def find_container_by_name(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    name_filter: str,
+) -> str | None:
+    """Find a running container by name filter and return its ID."""
+    url = f'{portainer_url}/api/endpoints/{endpoint_id}/docker/containers/json?filters={{"name":["{name_filter}"]}}'
+    response, status_code = api_request(url, api_key)
+
+    if 200 <= status_code < 300 and isinstance(response, list) and len(response) > 0:
+        return response[0].get("Id")
+    return None
+
+
+def get_network_id(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    network_name: str,
+) -> str | None:
+    """Find a network by name and return its ID."""
+    url = f'{portainer_url}/api/endpoints/{endpoint_id}/docker/networks?filters={{"name":["{network_name}"]}}'
+    response, status_code = api_request(url, api_key)
+
+    if 200 <= status_code < 300 and isinstance(response, list) and len(response) > 0:
+        return response[0].get("Id")
+    return None
+
+
+def create_exec(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    container_id: str,
+    cmd: list[str],
+) -> str | None:
+    """Create an exec instance in a container and return the exec ID."""
+    url = f"{portainer_url}/api/endpoints/{endpoint_id}/docker/containers/{container_id}/exec"
+    config = {
+        "AttachStdout": True,
+        "AttachStderr": True,
+        "Cmd": cmd,
+    }
+    response, status_code = api_request(url, api_key, method="POST", data=config)
+
+    if 200 <= status_code < 300 and response:
+        return response.get("Id")
+    return None
+
+
+def start_exec(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    exec_id: str,
+) -> tuple[int, str]:
+    """Start an exec instance and return (exit_code, output)."""
+    from urllib.request import Request, urlopen
+
+    url = f"{portainer_url}/api/endpoints/{endpoint_id}/docker/exec/{exec_id}/start"
+    headers = {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+    }
+    body = json.dumps({"Detach": False, "Tty": False}).encode("utf-8")
+    req = Request(url, data=body, headers=headers, method="POST")
+
+    try:
+        with urlopen(req) as response:
+            # Read raw output (has Docker stream headers like logs)
+            raw_output = response.read()
+            # Strip Docker stream headers
+            output = ""
+            i = 0
+            while i < len(raw_output):
+                if i + 8 <= len(raw_output):
+                    size = int.from_bytes(raw_output[i + 4 : i + 8], "big")
+                    if i + 8 + size <= len(raw_output):
+                        output += raw_output[i + 8 : i + 8 + size].decode(
+                            "utf-8", errors="replace"
+                        )
+                        i += 8 + size
+                        continue
+                break
+    except Exception as e:
+        return -1, f"Error: {e}"
+
+    # Get exec exit code
+    inspect_url = (
+        f"{portainer_url}/api/endpoints/{endpoint_id}/docker/exec/{exec_id}/json"
+    )
+    inspect_resp, _ = api_request(inspect_url, api_key)
+    exit_code = inspect_resp.get("ExitCode", -1) if inspect_resp else -1
+
+    return exit_code, output
+
+
+def run_ephemeral_container(
+    portainer_url: str,
+    api_key: str,
+    endpoint_id: int,
+    config: dict,
+    pull: bool = True,
+) -> tuple[int, str]:
+    """Run an ephemeral container and return (exit_code, logs)."""
+    image = config.get("Image")
+    if pull and image:
+        if not pull_image(portainer_url, api_key, endpoint_id, image):
+            print(f"Warning: Failed to pull image {image}, trying to run anyway...")
+
+    container_id = create_container(portainer_url, api_key, endpoint_id, config)
+    if not container_id:
+        return -1, "Failed to create container"
+
+    try:
+        if not start_container(portainer_url, api_key, endpoint_id, container_id):
+            return -1, "Failed to start container"
+
+        exit_code = wait_container(portainer_url, api_key, endpoint_id, container_id)
+        logs = get_container_logs(portainer_url, api_key, endpoint_id, container_id)
+
+        return exit_code, logs
+    finally:
+        remove_container(portainer_url, api_key, endpoint_id, container_id)

ptctools/_s3.py

@@ -0,0 +1,150 @@
+"""S3 utility functions for URI parsing and operations."""
+
+from __future__ import annotations
+
+import os
+import re
+from urllib.parse import urlparse
+
+import click
+
+
+def parse_s3_uri(uri: str) -> tuple[str | None, str, str]:
+    """Parse S3 URI into (endpoint, bucket, path).
+
+    Supports formats:
+    - s3://bucket/path
+    - s3://bucket/path?s3-server-name=endpoint
+    - s3://endpoint.com/bucket/path (endpoint detected by dots in first segment)
+    - https://endpoint.com/bucket/path
+
+    Returns:
+        Tuple of (endpoint or None, bucket, path)
+        - endpoint: The S3 endpoint URL or None if not specified
+        - bucket: The bucket name
+        - path: The object path within the bucket (may be empty)
+    """
+    if not uri:
+        raise click.ClickException("Empty S3 URI")
+
+    # Handle https:// or http:// scheme
+    if uri.startswith("https://") or uri.startswith("http://"):
+        parsed = urlparse(uri)
+        endpoint = f"{parsed.scheme}://{parsed.netloc}"
+        path_parts = parsed.path.strip("/").split("/", 1)
+        bucket = path_parts[0] if path_parts else ""
+        path = path_parts[1] if len(path_parts) > 1 else ""
+
+        if not bucket:
+            raise click.ClickException(f"Could not parse bucket from URI: {uri}")
+
+        return endpoint, bucket, path
+
+    # Handle s3:// scheme
+    if not uri.startswith("s3://"):
+        raise click.ClickException(
+            f"Invalid S3 URI format: {uri}. Expected s3://bucket/path or https://endpoint/bucket/path"
+        )
+
+    rest = uri[5:]  # Remove "s3://"
+
+    # Check for query parameter format: s3://bucket/path?s3-server-name=endpoint
+    if "?s3-server-name=" in rest:
+        match = re.match(r"([^/]+)/(.+?)\?s3-server-name=(.+)$", rest)
+        if match:
+            bucket = match.group(1)
+            path = match.group(2)
+            endpoint = match.group(3)
+            # Add https:// if not present
+            if not endpoint.startswith("http://") and not endpoint.startswith("https://"):
+                endpoint = f"https://{endpoint}"
+            return endpoint, bucket, path
+
+    # Split by first slash
+    parts = rest.split("/", 1)
+    first_part = parts[0]
+    remaining = parts[1] if len(parts) > 1 else ""
+
+    # Check if first part looks like an endpoint (has dots) or just bucket name
+    if "." in first_part:
+        # It's an endpoint like s3://minio.example.com/bucket/path
+        endpoint = f"https://{first_part}"
+        # remaining is now bucket/path
+        sub_parts = remaining.split("/", 1)
+        bucket = sub_parts[0] if sub_parts else ""
+        path = sub_parts[1] if len(sub_parts) > 1 else ""
+    else:
+        # It's just a bucket name like s3://bucket/path
+        endpoint = None
+        bucket = first_part
+        path = remaining
+
+    if not bucket:
+        raise click.ClickException(f"Could not parse bucket from S3 URI: {uri}")
+
+    return endpoint, bucket, path
+
+
+def is_s3_uri(path: str) -> bool:
+    """Check if path is an S3 URI."""
+    return path.startswith("s3://") or path.startswith("https://") or path.startswith("http://")
+
+
+def get_s3_endpoint(uri_endpoint: str | None, cli_endpoint: str | None = None) -> str:
+    """Get S3 endpoint from various sources.
+
+    Priority: CLI argument > URI embedded > environment variable
+
+    Args:
+        uri_endpoint: Endpoint parsed from URI (may be None)
+        cli_endpoint: Endpoint from CLI argument (may be None)
+
+    Returns:
+        The resolved endpoint URL
+
+    Raises:
+        ClickException if no endpoint can be resolved
+    """
+    endpoint = cli_endpoint or uri_endpoint or os.environ.get("S3_ENDPOINT")
+    if not endpoint:
+        raise click.ClickException(
+            "S3 endpoint required. Use --s3-endpoint, embed in URI (s3://endpoint/bucket), "
+            "or set S3_ENDPOINT environment variable"
+        )
+    return endpoint
+
+
+def get_s3_credentials() -> tuple[str, str]:
+    """Get S3 credentials from environment variables.
+
+    Returns:
+        Tuple of (access_key, secret_key)
+
+    Raises:
+        ClickException if credentials are missing
+    """
+    s3_access_key = os.environ.get("S3_ACCESS_KEY")
+    s3_secret_key = os.environ.get("S3_SECRET_KEY")
+    if not s3_access_key or not s3_secret_key:
+        raise click.ClickException(
+            "Missing S3_ACCESS_KEY or S3_SECRET_KEY environment variables"
+        )
+    return s3_access_key, s3_secret_key
+
+
+def build_duplicati_s3_url(bucket: str, path: str, endpoint: str) -> str:
+    """Build Duplicati-compatible S3 URL with query parameter.
+
+    Args:
+        bucket: S3 bucket name
+        path: Object path within bucket
+        endpoint: S3 endpoint URL
+
+    Returns:
+        Duplicati-compatible S3 URL like: s3://bucket/path?s3-server-name=host
+    """
+    s3_host = endpoint.replace("https://", "").replace("http://", "").rstrip("/")
+    if path:
+        return f"s3://{bucket}/{path}?s3-server-name={s3_host}"
+    else:
+        return f"s3://{bucket}?s3-server-name={s3_host}"

ptctools/cli.py

@@ -0,0 +1,28 @@
+"""Main CLI entry point for ptctools."""
+
+import click
+
+from ptctools import __version__
+from ptctools import stack
+from ptctools import volume
+from ptctools import db
+from ptctools import utils
+from ptctools import config
+
+
+@click.group()
+@click.version_option(version=__version__)
+def main():
+    """Portainer Client Tools - manage stacks, volumes, and databases."""
+    pass
+
+
+main.add_command(stack.cli, name="stack")
+main.add_command(volume.cli, name="volume")
+main.add_command(db.cli, name="db")
+main.add_command(utils.cli, name="utils")
+main.add_command(config.cli, name="config")
+
+
+if __name__ == "__main__":
+    main()