ptctools 0.2.0__tar.gz → 0.2.2__tar.gz

ptctools-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,139 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: New stable version, for example 0.2.2
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Release v${{ inputs.version }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+
+    steps:
+      - name: Check out main
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: main
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Validate release version
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+
+          python3 - <<'PY'
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          version = os.environ["RELEASE_VERSION"]
+          if not re.fullmatch(
+              r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)",
+              version,
+          ):
+              raise SystemExit("version must use the stable X.Y.Z format")
+
+          with Path("pyproject.toml").open("rb") as handle:
+              current = tomllib.load(handle)["project"]["version"]
+
+          parse = lambda value: tuple(int(part) for part in value.split("."))
+          if parse(version) <= parse(current):
+              raise SystemExit(
+                  f"release version {version} must be greater than current version {current}"
+              )
+
+          env_file = Path(os.environ["GITHUB_ENV"])
+          with env_file.open("a") as handle:
+              handle.write(f"VERSION={version}\n")
+              handle.write(f"TAG=v{version}\n")
+          PY
+
+          git fetch --tags --force origin
+          if git rev-parse --verify --quiet "refs/tags/v${RELEASE_VERSION}"; then
+            echo "tag v${RELEASE_VERSION} already exists" >&2
+            exit 1
+          fi
+
+      - name: Update package version
+        run: |
+          set -euo pipefail
+
+          uv version "$VERSION" --no-sync
+          python3 - <<'PY'
+          import os
+          import re
+          from pathlib import Path
+
+          path = Path("src/ptctools/__init__.py")
+          content = path.read_text()
+          updated, count = re.subn(
+              r'^__version__ = "[^"]+"$',
+              f'__version__ = "{os.environ["VERSION"]}"',
+              content,
+              count=1,
+              flags=re.MULTILINE,
+          )
+          if count != 1:
+              raise SystemExit("could not update exactly one __version__ assignment")
+          path.write_text(updated)
+          PY
+          uv lock
+
+      - name: Run tests
+        run: uv run --extra dev --locked pytest -q tests
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distributions
+        run: uvx --from twine twine check dist/*
+
+      - name: Commit and tag release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          gh auth setup-git --hostname github.com
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml uv.lock src/ptctools/__init__.py
+          git commit -m "chore(release): $TAG"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push --atomic origin HEAD:main "$TAG"
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          gh release create "$TAG" dist/* \
+            --title "$TAG" \
+            --generate-notes \
+            --verify-tag
+
+      - name: Publish distributions to PyPI
+        run: uv publish --trusted-publishing always

ptctools-0.2.2/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md - ptctools
+
+## Overview
+
+Portainer Client Tools CLI package for managing Portainer stacks, volumes, and databases from the command line.
+
+## Project Structure
+
+```text
+src/ptctools/
+├── pyproject.toml          # Package config, entry point: ptctools.cli:main
+├── README.md               # User documentation
+└── src/ptctools/
+    ├── __init__.py         # Version: 0.1.1
+    ├── cli.py              # Main click CLI, registers docker + utils groups
+    ├── docker.py           # Docker command group (registers stack, secret, config, volume, db)
+    ├── _portainer.py       # Shared Portainer API utilities (internal)
+    ├── _s3.py              # Shared S3/URI parsing utilities (internal)
+    ├── stack.py            # docker stack deploy command (Swarm-only)
+    ├── secret.py           # docker secret create command (Swarm-only)
+    ├── config.py           # docker config set/get/list/delete commands (Swarm-only)
+    ├── volume.py           # docker volume backup/restore/cp/rm/rename commands
+    ├── db.py               # docker db backup/restore commands
+    └── utils.py            # utils backup/restore commands (local Duplicati)
+```
+
+## CLI Architecture
+
+Uses [click](https://click.palletsprojects.com/) with nested command groups:
+
+```
+ptctools
+├── docker                    # Docker commands (via Portainer Docker proxy)
+│   ├── stack deploy         # Deploy/update stack (Swarm-only)
+│   ├── secret create        # Create Docker secret (Swarm-only)
+│   ├── config set/get/list/delete  # Manage configs (Swarm-only)
+│   ├── volume backup        # Backup volumes to S3 via Duplicati
+│   ├── volume restore       # Restore single volume from S3
+│   ├── volume cp            # Copy between volumes and S3
+│   ├── volume rm            # Remove volume
+│   ├── volume rename        # Rename volume (copy + delete)
+│   ├── db backup            # Backup PostgreSQL via container exec
+│   └── db restore           # Restore PostgreSQL from backup
+├── utils backup             # Local backup to S3 or directory using Duplicati
+├── utils restore            # Local restore from S3 or directory using Duplicati
+└── k8s ...                  # Kubernetes commands (future)
+```
+
+## Environment Variables
+
+All docker commands require `PORTAINER_ACCESS_TOKEN`. Backup commands also use:
+- `S3_ACCESS_KEY`, `S3_SECRET_KEY` - S3 credentials
+- `DUPLICATI_PASSPHRASE` - Optional encryption
+
+## Development
+
+```bash
+# Install in development mode
+uv tool install . --force
+
+# Test CLI
+ptctools --help
+ptctools docker --help
+```
+
+## Adding New Commands
+
+### Adding a Docker subcommand
+1. Create module in `src/ptctools/` with a `cli` click group
+2. Register in `docker.py` via `cli.add_command(module.cli, name="name")`
+3. Use `_portainer.py` for Portainer API calls
+
+### Adding a new top-level group (e.g., k8s)
+1. Create module in `src/ptctools/` with a `cli` click group
+2. Register in `cli.py` via `main.add_command(module.cli, name="name")`

{ptctools-0.2.0 → ptctools-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ptctools
-Version: 0.2.0
+Version: 0.2.2
 Summary: Portainer Client Tools - CLI for managing Portainer from client
 License-File: LICENSE
 Requires-Python: >=3.10
@@ -102,6 +102,10 @@ ptctools docker db restore -c container_id -v db_data \
 ptctools docker db restore -c container_id -v db_data \
   --db-user postgres --db-name mydb -i s3://mybucket/backups/db.sql.gz
 
+# Clean up exited containers and unused images
+ptctools docker clean
+ptctools docker clean -y  # skip confirmation
+
 # Override PORTAINER_URL with -u flag
 ptctools docker secret create -u https://other.portainer.com -f dsn.txt my_secret
 
@@ -120,7 +124,8 @@ ptctools
 │   ├── secret create        # Create Docker secret (Swarm-only)
 │   ├── config set/get/list/delete  # Manage configs (Swarm-only)
 │   ├── volume backup/restore/cp/rm/rename
-│   └── db backup/restore
+│   ├── db backup/restore
+│   └── clean                # Remove exited containers & unused images
 ├── utils backup/restore     # Local Duplicati operations
 └── k8s ...                  # Kubernetes commands (future)
 ```
@@ -158,5 +163,28 @@ Backup/restore PostgreSQL database. Supports both local files and S3 URIs.
 - Uses `pg_dump`/`psql` for database operations
 - Uses `minio/mc` container for S3 transfers
 
+### `ptctools docker clean`
+Remove all exited containers and unused (dangling) images. Use `-y` to skip confirmation.
+
 ### `ptctools utils backup/restore`
 Local backup/restore operations using Duplicati CLI (docker or local). Does not require Portainer.
+
+## Releasing
+
+The `Release` GitHub Actions workflow creates a new stable release from `main`.
+Run it from the Actions tab and provide a canonical version in `X.Y.Z` format
+(without leading zeroes), such as `0.2.2`. The workflow:
+
+1. Requires the requested version to be greater than the current package version.
+2. Updates `pyproject.toml`, `uv.lock`, and `src/ptctools/__init__.py`.
+3. Runs the test suite and builds the wheel and source distribution.
+4. Commits the version change to `main` and creates an annotated `vX.Y.Z` tag.
+5. Creates a GitHub Release with generated notes and both distribution files.
+6. Publishes the same distribution files to PyPI through Trusted Publishing.
+
+The workflow uses the repository `GITHUB_TOKEN` for GitHub and an ephemeral OIDC
+token for PyPI; no additional release secret is required. The PyPI Trusted
+Publisher must authorize repository `tamntlib/ptctools` and workflow
+`release.yml`, with environment `pypi`. A failed test, invalid version, existing
+tag, or distribution check stops the release before the commit and tag are
+pushed.

{ptctools-0.2.0 → ptctools-0.2.2}/README.md

@@ -88,6 +88,10 @@ ptctools docker db restore -c container_id -v db_data \
 ptctools docker db restore -c container_id -v db_data \
   --db-user postgres --db-name mydb -i s3://mybucket/backups/db.sql.gz
 
+# Clean up exited containers and unused images
+ptctools docker clean
+ptctools docker clean -y  # skip confirmation
+
 # Override PORTAINER_URL with -u flag
 ptctools docker secret create -u https://other.portainer.com -f dsn.txt my_secret
 
@@ -106,7 +110,8 @@ ptctools
 │   ├── secret create        # Create Docker secret (Swarm-only)
 │   ├── config set/get/list/delete  # Manage configs (Swarm-only)
 │   ├── volume backup/restore/cp/rm/rename
-│   └── db backup/restore
+│   ├── db backup/restore
+│   └── clean                # Remove exited containers & unused images
 ├── utils backup/restore     # Local Duplicati operations
 └── k8s ...                  # Kubernetes commands (future)
 ```
@@ -144,5 +149,28 @@ Backup/restore PostgreSQL database. Supports both local files and S3 URIs.
 - Uses `pg_dump`/`psql` for database operations
 - Uses `minio/mc` container for S3 transfers
 
+### `ptctools docker clean`
+Remove all exited containers and unused (dangling) images. Use `-y` to skip confirmation.
+
 ### `ptctools utils backup/restore`
 Local backup/restore operations using Duplicati CLI (docker or local). Does not require Portainer.
+
+## Releasing
+
+The `Release` GitHub Actions workflow creates a new stable release from `main`.
+Run it from the Actions tab and provide a canonical version in `X.Y.Z` format
+(without leading zeroes), such as `0.2.2`. The workflow:
+
+1. Requires the requested version to be greater than the current package version.
+2. Updates `pyproject.toml`, `uv.lock`, and `src/ptctools/__init__.py`.
+3. Runs the test suite and builds the wheel and source distribution.
+4. Commits the version change to `main` and creates an annotated `vX.Y.Z` tag.
+5. Creates a GitHub Release with generated notes and both distribution files.
+6. Publishes the same distribution files to PyPI through Trusted Publishing.
+
+The workflow uses the repository `GITHUB_TOKEN` for GitHub and an ephemeral OIDC
+token for PyPI; no additional release secret is required. The PyPI Trusted
+Publisher must authorize repository `tamntlib/ptctools` and workflow
+`release.yml`, with environment `pypi`. A failed test, invalid version, existing
+tag, or distribution check stops the release before the commit and tag are
+pushed.

{ptctools-0.2.0 → ptctools-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ptctools"
-version = "0.2.0"
+version = "0.2.2"
 description = "Portainer Client Tools - CLI for managing Portainer from client"
 readme = "README.md"
 requires-python = ">=3.10"

{ptctools-0.2.0 → ptctools-0.2.2}/src/ptctools/__init__.py

@@ -1,6 +1,6 @@
 """Portainer Client Tools - CLI for managing Portainer stacks and backups."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.2"
 
 import sys
 import os

{ptctools-0.2.0 → ptctools-0.2.2}/src/ptctools/_portainer.py

@@ -109,8 +109,10 @@ def get_portainer_docker_client(
     api_client.mount("http://", adapter)
     api_client.mount("https://", adapter)
 
-    # Wrap in high-level client
-    client = docker.DockerClient()
+    # DockerClient.__init__ creates another APIClient and probes the local
+    # Docker daemon. Build only the high-level wrapper and attach the
+    # Portainer-proxied API client directly.
+    client = docker.DockerClient.__new__(docker.DockerClient)
     client.api = api_client
 
     return client
@@ -119,9 +121,11 @@ def get_portainer_docker_client(
 def get_portainer_api_client(portainer_url: str, api_key: str) -> ApiClient:
     """Create a configured ApiClient for Portainer API."""
     config = Configuration(
-        host=f"{portainer_url.rstrip('/')}/api", api_key={"ApiKeyAuth": api_key}
+        host=f"{portainer_url.rstrip('/')}/api",
     )
-    return ApiClient(configuration=config)
+    client = ApiClient(configuration=config)
+    client.default_headers["X-API-Key"] = api_key
+    return client
 
 
 def set_volume_ownership(

ptctools-0.2.2/src/ptctools/clean.py

@@ -0,0 +1,159 @@
+"""Docker cleanup commands - remove exited containers and unused images."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+import docker.errors
+
+from ptctools._portainer import (
+    get_portainer_docker_client,
+    get_portainer_api_client,
+    PortainerError,
+)
+from ptctools.portainer_client.openapi_client.api.docker_api import DockerApi
+
+
+class CleanError(PortainerError):
+    """Exception for clean operations."""
+
+    pass
+
+
+@click.command()
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
+@click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
+@click.option(
+    "--yes",
+    "-y",
+    is_flag=True,
+    default=False,
+    help="Skip confirmation prompt",
+)
+def cli(url: str, endpoint_id: int, yes: bool):
+    """Remove all exited containers and unused images.
+
+    This command cleans up Docker resources by:
+    1. Removing all containers in 'exited' state
+    2. Removing all images not referenced by any container
+
+    Example:
+        ptctools docker clean
+        ptctools docker clean -y  # skip confirmation
+    """
+    access_token = os.environ.get("PORTAINER_ACCESS_TOKEN")
+    if not access_token:
+        click.echo(
+            "Error: Missing PORTAINER_ACCESS_TOKEN environment variable", err=True
+        )
+        sys.exit(1)
+
+    portainer_url = url.rstrip("/")
+
+    click.echo(f"Portainer URL: {portainer_url}")
+    click.echo(f"Endpoint ID: {endpoint_id}")
+    click.echo()
+
+    try:
+        docker_client = get_portainer_docker_client(
+            portainer_url, access_token, endpoint_id
+        )
+
+        # --- Discover exited containers ---
+        exited_containers = docker_client.containers.list(
+            all=True, filters={"status": "exited"}
+        )
+
+        # --- Discover unused images via Portainer API ---
+        with get_portainer_api_client(portainer_url, access_token) as api_client:
+            docker_api = DockerApi(api_client)
+            all_images = docker_api.docker_images_list(
+                environment_id=endpoint_id, with_usage=True
+            ).data
+        unused_images = [img for img in all_images if not img.used]
+
+        if not exited_containers and not unused_images:
+            click.echo("Nothing to clean up.")
+            sys.exit(0)
+
+        # --- Show summary ---
+        if exited_containers:
+            click.echo(f"Exited containers ({len(exited_containers)}):")
+            for c in exited_containers:
+                name = c.name or c.short_id
+                image = c.image.tags[0] if c.image.tags else c.attrs.get("Image", "unknown")[:20]
+                click.echo(f"  - {name} ({c.short_id}) [{image}]")
+            click.echo()
+
+        if unused_images:
+            click.echo(f"Unused images ({len(unused_images)}):")
+            for img in unused_images:
+                tags = img.tags or []
+                display_tag = tags[0].split("@")[0] if tags else "<none>"
+                img_id = img.id[:19]  # sha256:xxxx (first 12 hex)
+                click.echo(f"  - {img_id} [{display_tag}]")
+            click.echo()
+
+        # --- Confirm ---
+        if not yes:
+            click.confirm("Proceed with cleanup?", abort=True)
+            click.echo()
+
+        # --- Remove exited containers ---
+        removed_containers = 0
+        for c in exited_containers:
+            name = c.name or c.short_id
+            try:
+                c.remove(force=True)
+                click.echo(f"  Removed container: {name} ({c.short_id})")
+                removed_containers += 1
+            except docker.errors.APIError as e:
+                click.echo(
+                    f"  Failed to remove container {name}: {e.explanation or str(e)}",
+                    err=True,
+                )
+
+        if removed_containers:
+            click.echo(f"Removed {removed_containers} container(s).")
+            click.echo()
+
+        # --- Remove unused images ---
+        removed_images = 0
+        for img in unused_images:
+            tags = img.tags or []
+            display_tag = tags[0].split("@")[0] if tags else img.id[:19]
+            try:
+                docker_client.images.remove(image=img.id, force=True)
+                click.echo(f"  Removed image: {display_tag}")
+                removed_images += 1
+            except docker.errors.APIError as e:
+                click.echo(
+                    f"  Failed to remove image {display_tag}: {e.explanation or str(e)}",
+                    err=True,
+                )
+
+        if removed_images:
+            click.echo(f"Removed {removed_images} image(s).")
+            click.echo()
+
+        click.echo("Done!")
+        sys.exit(0)
+
+    except docker.errors.APIError as e:
+        click.echo(f"Error: {e.explanation or str(e)}", err=True)
+        click.echo()
+        click.echo("Failed!")
+        sys.exit(1)
+    except CleanError as e:
+        click.echo(f"Error: {e}", err=True)
+        click.echo()
+        click.echo("Failed!")
+        sys.exit(1)