ptctools 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ptctools
-Version: 0.2.2
+Version: 0.2.3
 Summary: Portainer Client Tools - CLI for managing Portainer from client
 License-File: LICENSE
 Requires-Python: >=3.10
@@ -37,6 +37,22 @@ openapi-generator-cli generate \
 uv tool install . --no-cache --reinstall
 ```
 
+## Stack deployment status
+
+Portainer can return a stack while deployment is still in progress. The bundled
+OpenAPI schema and client recognize `Active=1`, `Inactive=2`, `Deploying=3`, and
+`Error=4` (plus the legacy unspecified value `0`).
+
+`docker stack deploy` reports **submitted**, not verified service health. A
+`Deploying` response is accepted without retrying the deployment; requested
+ownership updates still run. An `Error` response exits non-zero before subsequent
+ownership writes. The command does not wait for deployment completion or poll
+service health, so exit code zero is not a health check. Stack response environment
+values are not printed.
+
+If an older client crashes decoding a response after submission, inspect the
+stack and its services before retrying: the server may already have applied it.
+
 ## Environment Variables
 
 | Variable | Required | Description |

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

@@ -23,6 +23,22 @@ openapi-generator-cli generate \
 uv tool install . --no-cache --reinstall
 ```
 
+## Stack deployment status
+
+Portainer can return a stack while deployment is still in progress. The bundled
+OpenAPI schema and client recognize `Active=1`, `Inactive=2`, `Deploying=3`, and
+`Error=4` (plus the legacy unspecified value `0`).
+
+`docker stack deploy` reports **submitted**, not verified service health. A
+`Deploying` response is accepted without retrying the deployment; requested
+ownership updates still run. An `Error` response exits non-zero before subsequent
+ownership writes. The command does not wait for deployment completion or poll
+service health, so exit code zero is not a health check. Stack response environment
+values are not printed.
+
+If an older client crashes decoding a response after submission, inspect the
+stack and its services before retrying: the server may already have applied it.
+
 ## Environment Variables
 
 | Variable | Required | Description |

{ptctools-0.2.2 → ptctools-0.2.3}/portainer_openapi.yml

@@ -3890,11 +3890,15 @@ definitions:
     - 0
     - 1
     - 2
+    - 3
+    - 4
     type: integer
     x-enum-varnames:
     - _
     - StackStatusActive
     - StackStatusInactive
+    - StackStatusDeploying
+    - StackStatusError
   portainer.StackType:
     enum:
     - 0

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

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

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

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

{ptctools-0.2.2 → ptctools-0.2.3}/src/ptctools/portainer_client/openapi_client/docs/PortainerStackStatus.md

@@ -9,6 +9,10 @@
 
 * `StackStatusInactive` (value: `2`)
 
+* `StackStatusDeploying` (value: `3`)
+
+* `StackStatusError` (value: `4`)
+
 [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
 
 

{ptctools-0.2.2 → ptctools-0.2.3}/src/ptctools/portainer_client/openapi_client/models/portainer_stack_status.py

@@ -30,6 +30,8 @@ class PortainerStackStatus(int, Enum):
     _ = 0
     StackStatusActive = 1
     StackStatusInactive = 2
+    StackStatusDeploying = 3
+    StackStatusError = 4
 
     @classmethod
     def from_json(cls, json_str: str) -> Self:

{ptctools-0.2.2 → ptctools-0.2.3}/src/ptctools/stack.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 import logging
 import os
 import sys
@@ -37,6 +36,10 @@ from ptctools.portainer_client.openapi_client.models.resourcecontrols_resource_c
 from ptctools.portainer_client.openapi_client.models.portainer_resource_control_type import (
     PortainerResourceControlType,
 )
+from ptctools.portainer_client.openapi_client.models.portainer_stack import PortainerStack
+from ptctools.portainer_client.openapi_client.models.portainer_stack_status import (
+    PortainerStackStatus,
+)
 from ptctools.portainer_client.openapi_client.exceptions import ApiException
 
 logger = logging.getLogger(__name__)
@@ -48,6 +51,20 @@ class StackError(PortainerError):
     pass
 
 
+def _report_stack_submission(response: PortainerStack) -> None:
+    """Report API acceptance without claiming asynchronous deployment health."""
+    if response.status == PortainerStackStatus.StackStatusError:
+        raise StackError(
+            "Portainer reports deployment failed (stack status: error); "
+            "inspect the stack before retrying"
+        )
+    if response.status == PortainerStackStatus.StackStatusDeploying:
+        click.echo("Stack deployment submitted; deployment is still in progress.")
+    else:
+        click.echo("Stack deployment submitted.")
+    click.echo("Remote service health is not verified; inspect the stack in Portainer.")
+
+
 def _normalize_env_value(raw_value: str) -> str:
     """Normalize a .env value by trimming whitespace and matching quotes."""
     value = raw_value.strip()
@@ -207,8 +224,7 @@ def deploy(
                     endpoint_id=endpoint_id,
                     body=payload.to_dict(),
                 )
-                click.echo("Stack updated successfully!")
-                click.echo(json.dumps(response.to_dict(), indent=2))
+                _report_stack_submission(response)
             else:
                 # Create new stack - need swarm ID first
                 click.echo("Getting swarm ID...")
@@ -231,8 +247,7 @@ def deploy(
                 response = stacks_api.stack_create_docker_swarm_string(
                     endpoint_id=endpoint_id, body=payload.to_dict()
                 )
-                click.echo("Stack created successfully!")
-                click.echo(json.dumps(response.to_dict(), indent=2))
+                _report_stack_submission(response)
 
             # Apply access control
             if ownership:

ptctools-0.2.3/tests/test_stack_deploy.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from urllib.parse import urlsplit
+
+import pytest
+from click.testing import CliRunner
+from urllib3 import HTTPResponse
+
+from ptctools import stack as stack_module
+from ptctools._portainer import get_portainer_api_client
+from ptctools.cli import main
+from ptctools.portainer_client.openapi_client.rest import RESTResponse
+
+
+@pytest.fixture
+def invoke_deploy(monkeypatch, tmp_path):
+    """Exercise CLI + generated SDK; replace only the HTTP transport."""
+    stack_file = tmp_path / "compose.yaml"
+    stack_file.write_text("version: '3.8'\nservices:\n  app:\n    image: example:latest\n")
+    env_file = tmp_path / "stack.env"
+    env_file.write_text("APP_KEY=test-env-secret\n")
+    monkeypatch.setenv("PORTAINER_ACCESS_TOKEN", "test-token")
+    monkeypatch.setattr(
+        stack_module,
+        "get_portainer_docker_client",
+        lambda *args: SimpleNamespace(swarm=SimpleNamespace(attrs={"ID": "swarm-test"})),
+    )
+
+    def invoke(status, *, create=False, ownership=False):
+        calls = []
+        submitted = False
+        response_stack = {
+            "Id": 6,
+            "Name": "example",
+            "EndpointId": 1,
+            "Status": status,
+            "Env": [{"name": "APP_KEY", "value": "test-env-secret"}],
+            "ResourceControl": {"Id": 56},
+        }
+
+        def request(method, url, **kwargs):
+            nonlocal submitted
+            path = urlsplit(url).path
+            calls.append((method, path, kwargs.get("body")))
+            if method == "GET" and path == "/api/stacks":
+                data = [] if create and not submitted else [response_stack]
+            elif method == "GET" and path == "/api/stacks/6":
+                data = response_stack
+            elif (method, path) in {
+                ("PUT", "/api/stacks/6"),
+                ("POST", "/api/stacks/create/swarm/string"),
+            }:
+                submitted = True
+                data = response_stack
+            elif method == "PUT" and path == "/api/resource_controls/56":
+                data = {"Id": 56, "TeamAccesses": [{"TeamId": 2, "AccessLevel": 1}]}
+            else:
+                raise AssertionError(f"Unexpected request: {method} {path}")
+            return RESTResponse(
+                HTTPResponse(
+                    body=json.dumps(data).encode(),
+                    status=200,
+                    headers={"content-type": "application/json"},
+                )
+            )
+
+        def client_factory(url, token):
+            client = get_portainer_api_client(url, token)
+            monkeypatch.setattr(client.rest_client, "request", request)
+            return client
+
+        monkeypatch.setattr(stack_module, "get_portainer_api_client", client_factory)
+        args = [
+            "docker", "stack", "deploy", "--url", "https://portainer.example.test",
+            "-n", "example", "-f", str(stack_file), "--env-file", str(env_file),
+        ]
+        if ownership:
+            args.extend(["--ownership", "team", "--team-id", "2"])
+        return CliRunner().invoke(main, args), calls
+
+    return invoke
+
+
+@pytest.mark.parametrize("create", [False, True], ids=["update", "create"])
+def test_deploying_response_reports_submission_and_preserves_ownership(
+    invoke_deploy, create
+):
+    result, calls = invoke_deploy(3, create=create, ownership=True)
+
+    assert result.exit_code == 0, result.output
+    assert "submitted" in result.output.lower()
+    assert "in progress" in result.output.lower()
+    assert "not verified" in result.output.lower()
+    assert "successfully" not in result.output.lower()
+    assert "test-env-secret" not in result.output
+    assert "test-token" not in result.output
+    writes = [(method, path, body) for method, path, body in calls if method != "GET"]
+    assert len(writes) == 2  # one deployment, then ownership; never retry the write
+    assert writes[-1][1] == "/api/resource_controls/56"
+    assert writes[-1][2]["teams"] == [2]
+    if not create:
+        assert writes[0][2]["prune"] is True
+        assert writes[0][2]["pullImage"] is True
+
+
+@pytest.mark.parametrize("create", [False, True], ids=["update", "create"])
+def test_error_response_fails_without_false_success_or_followup_writes(
+    invoke_deploy, create
+):
+    result, calls = invoke_deploy(4, create=create, ownership=True)
+
+    assert result.exit_code == 1, result.output
+    assert "deployment failed" in result.output.lower()
+    assert "successfully" not in result.output.lower()
+    assert "Done!" not in result.output
+    assert "test-env-secret" not in result.output
+    assert len([c for c in calls if c[0] != "GET"]) == 1
+
+
+def test_active_response_does_not_claim_service_health(invoke_deploy):
+    result, _ = invoke_deploy(1)
+
+    assert result.exit_code == 0, result.output
+    assert "submitted" in result.output.lower()
+    assert "not verified" in result.output.lower()
+    assert "test-env-secret" not in result.output

ptctools-0.2.3/tests/test_stack_status.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import cast
+
+import pytest
+from pydantic import ValidationError
+
+from ptctools.portainer_client.openapi_client import ApiClient
+from ptctools.portainer_client.openapi_client.models.portainer_stack import PortainerStack
+from ptctools.portainer_client.openapi_client.models.portainer_stack_status import (
+    PortainerStackStatus,
+)
+
+
+@pytest.mark.parametrize(
+    ("value", "name"),
+    [(3, "StackStatusDeploying"), (4, "StackStatusError")],
+)
+def test_deserialize_async_stack_status(value: int, name: str) -> None:
+    with ApiClient() as client:
+        stack = cast(
+            PortainerStack,
+            client.deserialize(
+                json.dumps({"Id": 6, "Name": "example", "Status": value}),
+                "PortainerStack",
+                "application/json",
+            ),
+        )
+
+    assert stack.status is not None
+    assert stack.status.name == name
+    assert stack.to_dict()["Status"] == value
+
+
+@pytest.mark.parametrize("value", [0, 1, 2])
+def test_legacy_stack_status_still_deserializes(value: int) -> None:
+    with ApiClient() as client:
+        stack = cast(
+            PortainerStack,
+            client.deserialize(
+                json.dumps({"Status": value}), "PortainerStack", "application/json"
+            ),
+        )
+    assert stack.status is not None
+    assert stack.status.value == value
+
+
+def test_unknown_stack_status_is_not_silently_accepted() -> None:
+    with ApiClient() as client, pytest.raises(ValidationError, match="Status"):
+        client.deserialize('{"Status": 99}', "PortainerStack", "application/json")
+
+
+def test_stack_status_schema_matches_generated_enum() -> None:
+    schema = (Path(__file__).parents[1] / "portainer_openapi.yml").read_text()
+    status_schema = schema.split("  portainer.StackStatus:\n", 1)[1].split(
+        "  portainer.StackType:\n", 1
+    )[0]
+    values, names = status_schema.split("    x-enum-varnames:\n")
+    schema_values = [int(line[6:]) for line in values.splitlines() if line.startswith("    - ")]
+    schema_names = [line[6:] for line in names.splitlines() if line.startswith("    - ")]
+
+    assert dict(zip(schema_names, schema_values, strict=True)) == {
+        member.name: member.value for member in PortainerStackStatus
+    }

{ptctools-0.2.2 → ptctools-0.2.3}/uv.lock

@@ -194,7 +194,7 @@ wheels = [
 
 [[package]]
 name = "ptctools"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "click" },