python-corekit 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/http/client.py

@@ -1,7 +1,10 @@
 """
 A small HTTP client with retries.
 
-Subclass and give it a base URL::
+``BaseHttpClient`` is the transport: relative paths, optional strict URL
+checking, and retries for statuses the typed HTTP exceptions mark as
+retryable. Subclass ``BaseApiClient`` when the client always talks to one
+API and a foreign absolute URL should be a bug.
 
     class GithubClient(BaseApiClient):
         '''
@@ -17,46 +20,79 @@ Subclass and give it a base URL::
             return {"Authorization": f"Bearer {self.token}"}
 
     client = GithubClient()
-    response = client.get("/user")          # or await client.async_get("/user")
+    response = client.get("/user")          # or await client.get("/user")
     response.data["login"]
 
 Every response comes back as a ``BaseApiResponse``, so callers see one shape
-regardless of what the endpoint returned. Requests that fail with a retryable
-status are retried with exponential backoff.
+regardless of what the endpoint returned.
 """
 
 from http import HTTPMethod
 from typing import Any
-from urllib.parse import urljoin
+from urllib.parse import urljoin, urlsplit, urlunsplit
 
 import httpx
 
+from corekit.concurrency.decorators import allow_sync
+from corekit.http.exceptions import RETRYABLE_STATUS_CODES, UnsupportedMethodError, URLMismatchError
 from corekit.http.exponential_backoff import ExponentialBackoff
 from corekit.http.response import BaseApiResponse
+from corekit.http.status import HTTPStatusCode
 from corekit.observability.benchmarkable import Benchmarkable
 
-__all__ = ["BaseApiClient", "URLMismatchError"]
+__all__ = ["BaseHttpClient"]
 
-# Statuses worth retrying: the server is busy or briefly unavailable, so the
-# same request may well succeed shortly. A 4xx other than 429 will not.
-RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
 
-
-class URLMismatchError(Exception):
+def _without_query(url: str) -> str:
     """
-    Raised when an absolute URL is passed that does not share the base URL.
+    Drop the query string before a retry warning is logged.
     """
+    parts = urlsplit(url)
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, "", ""))
+
 
+_DEFAULT_METHODS = frozenset(
+    {
+        HTTPMethod.GET,
+        HTTPMethod.POST,
+        HTTPMethod.PUT,
+        HTTPMethod.PATCH,
+        HTTPMethod.DELETE,
+    }
+)
 
-class BaseApiClient(Benchmarkable):
+
+class BaseHttpClient(Benchmarkable):
     """
-    Base for API clients. Override ``base_url`` and, usually, ``headers``.
+    Base for HTTP clients. Override ``base_url`` and, usually, ``headers``.
+
+    ``strict=False`` accepts a foreign absolute URL as-is. ``BaseApiClient``
+    turns that into an error.
     """
 
-    def __init__(self, retries: int = 3, timeout: float = 30.0) -> None:
+    def __init__(
+        self,
+        retries: int = 3,
+        timeout: float = 30.0,
+        strict: bool = False,
+        base_delay: float = 1,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
         super().__init__()
         self.retries = retries
         self.timeout = timeout
+        self.strict = strict
+        self.base_delay = base_delay
+        # Optional pool. Left unset by default: @allow_sync runs sync calls on a
+        # throwaway loop, and an AsyncClient cannot move between loops.
+        self._http_client = http_client
+
+    @property
+    def supported_methods(self) -> frozenset[HTTPMethod]:
+        """
+        HTTP methods this client will send. Override to narrow or extend the set.
+        """
+        return _DEFAULT_METHODS
 
     @property
     def headers(self) -> dict[str, str]:
@@ -77,16 +113,18 @@ class BaseApiClient(Benchmarkable):
         Resolve a path against the base URL, accepting an absolute URL that
         already matches it.
         """
-        if url.startswith(self.base_url):
+        if self.base_url and url.startswith(self.base_url):
             return url
         if url.startswith("http"):
-            raise URLMismatchError(f"URL {url} does not match base URL {self.base_url}")
+            if self.strict:
+                raise URLMismatchError(url, self.base_url)
+            return url
         return urljoin(self.base_url, url)
 
     @staticmethod
-    def _to_response(raw: Any) -> BaseApiResponse:
+    def _to_response(raw: httpx.Response) -> BaseApiResponse:
         """
-        Normalize an httpx response into a BaseApiResponse.
+        Normalize a httpx response into a BaseApiResponse.
 
         The body is decoded as JSON when it parses, and left as text otherwise,
         so a caller never has to guard against a non-JSON error page.
@@ -99,78 +137,67 @@ class BaseApiClient(Benchmarkable):
             data = {"data": data}
 
         return BaseApiResponse(
-            status_code=raw.status_code,
+            status_code=HTTPStatusCode.coerce(raw.status_code),
             text=raw.text,
             data=data,
             headers=dict(raw.headers),
             cookies=dict(raw.cookies),
         )
 
-    def _new_backoff(self) -> ExponentialBackoff:
-        return ExponentialBackoff(retries=self.retries)
-
-    def request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
-        """
-        Send a request, retrying retryable statuses.
-        """
-
-        target = self._build_url(url)
-        backoff = self._new_backoff()
-
-        while True:
-            with httpx.Client(timeout=self.timeout) as client:
-                raw = client.request(str(method), target, headers=self.headers, **kwargs)
-
-            if raw.status_code not in RETRYABLE_STATUS_CODES or backoff.did_timeout():
-                return self._to_response(raw)
-
-            self.warning(f"{method} {target} returned {raw.status_code}; retrying")
-            backoff.wait()
-
-    async def async_request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
+    async def request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
         """
         Send a request asynchronously, retrying retryable statuses.
         """
+        if method not in self.supported_methods:
+            raise UnsupportedMethodError(method)
 
         target = self._build_url(url)
-        backoff = self._new_backoff()
-
+        headers = dict(self.headers)
+        extra_headers = kwargs.pop("headers", None)
+        if extra_headers:
+            headers.update(extra_headers)
+        # Fresh each request: ExponentialBackoff keeps its own attempt count.
+        backoff = ExponentialBackoff(retries=self.retries, base_delay=self.base_delay)
+
+        if self._http_client is not None:
+            return await self._exchange(self._http_client, method, target, headers, backoff, kwargs)
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            return await self._exchange(client, method, target, headers, backoff, kwargs)
+
+    async def _exchange(
+        self,
+        client: httpx.AsyncClient,
+        method: HTTPMethod,
+        target: str,
+        headers: dict[str, str],
+        backoff: ExponentialBackoff,
+        kwargs: dict[str, Any],
+    ) -> BaseApiResponse:
         while True:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                raw = await client.request(str(method), target, headers=self.headers, **kwargs)
-
+            raw = await client.request(str(method), target, headers=headers, **kwargs)
             if raw.status_code not in RETRYABLE_STATUS_CODES or backoff.did_timeout():
                 return self._to_response(raw)
 
-            self.warning(f"{method} {target} returned {raw.status_code}; retrying")
+            self.warning(f"{method} {_without_query(target)} returned {raw.status_code}; retrying")
             await backoff.async_wait()
 
-    def get(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.GET, url, **kwargs)
-
-    def post(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.POST, url, **kwargs)
-
-    def put(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.PUT, url, **kwargs)
-
-    def patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.PATCH, url, **kwargs)
-
-    def delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.DELETE, url, **kwargs)
-
-    async def async_get(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.GET, url, **kwargs)
+    @allow_sync
+    async def get(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.GET, url, **kwargs)
 
-    async def async_post(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.POST, url, **kwargs)
+    @allow_sync
+    async def post(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.POST, url, **kwargs)
 
-    async def async_put(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.PUT, url, **kwargs)
+    @allow_sync
+    async def put(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.PUT, url, **kwargs)
 
-    async def async_patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.PATCH, url, **kwargs)
+    @allow_sync
+    async def patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.PATCH, url, **kwargs)
 
-    async def async_delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.DELETE, url, **kwargs)
+    @allow_sync
+    async def delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.DELETE, url, **kwargs)

corekit/http/exceptions.py

@@ -0,0 +1,140 @@
+"""
+HTTP-specific exceptions.
+
+These live here, not in ``corekit.exceptions``, so the exception package does
+not have to import this layer. The bases (``CoreHTTPException`` and the
+retryable / non-retryable variants) still come from there.
+"""
+
+from http import HTTPMethod
+from typing import Any
+
+from corekit.exceptions.base import (
+    InternalCoreException,
+    NonRetryableCoreHTTPException,
+    RetryableCoreHTTPException,
+)
+from corekit.exceptions.enum import Retryability
+from corekit.http.status import HTTPStatusCode
+
+__all__ = [
+    "BadGatewayException",
+    "BadRequestException",
+    "ConflictErrorException",
+    "ForbiddenException",
+    "GatewayTimeoutException",
+    "InternalServerErrorException",
+    "NotFoundException",
+    "ServiceUnavailableException",
+    "TooManyRequestsException",
+    "UnauthorizedException",
+    "UnprocessableEntityException",
+    "UnsupportedMediaTypeException",
+    "UnsupportedMethodError",
+    "URLMismatchError",
+    "RETRYABLE_STATUS_CODES",
+]
+
+
+class _CodedHTTPException:
+    """
+    Sets ``status_code`` from the class. The code is the type, so a caller
+    cannot pass a different one and have a ``GatewayTimeoutException`` that is
+    actually a 200.
+    """
+
+    code: HTTPStatusCode
+
+    def __init__(self, **kwargs: Any) -> None:
+        if "status_code" in kwargs:
+            raise TypeError(f"{type(self).__name__} does not accept status_code; it is always {int(self.code)}")
+        super().__init__(status_code=self.code, **kwargs)
+
+
+class BadRequestException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.BAD_REQUEST
+
+
+class UnauthorizedException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNAUTHORIZED
+
+
+class ForbiddenException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.FORBIDDEN
+
+
+class NotFoundException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.NOT_FOUND
+
+
+class ConflictErrorException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.CONFLICT
+
+
+class UnsupportedMediaTypeException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNSUPPORTED_MEDIA_TYPE
+
+
+class UnprocessableEntityException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNPROCESSABLE_ENTITY
+
+
+class TooManyRequestsException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.TOO_MANY_REQUESTS
+
+
+class InternalServerErrorException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.INTERNAL_SERVER_ERROR
+
+
+class BadGatewayException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.BAD_GATEWAY
+
+
+class ServiceUnavailableException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.SERVICE_UNAVAILABLE
+
+
+class GatewayTimeoutException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.GATEWAY_TIMEOUT
+
+
+# Statuses worth retrying: the server is busy or briefly unavailable, so the
+# same request may well succeed shortly. A 4xx other than 429 will not.
+# Derived from the typed exceptions so this set cannot drift from retryability.
+RETRYABLE_STATUS_CODES = frozenset(
+    {
+        TooManyRequestsException.code,
+        InternalServerErrorException.code,
+        BadGatewayException.code,
+        ServiceUnavailableException.code,
+        GatewayTimeoutException.code,
+    }
+)
+
+
+class URLMismatchError(InternalCoreException):
+    """
+    Raised when an absolute URL does not share the client's base URL.
+    """
+
+    def __init__(self, url: str, base_url: str) -> None:
+        super().__init__(
+            message=f"URL {url} does not match base URL {base_url}",
+            retryable=Retryability.NON_RETRYABLE,
+        )
+        self.url = url
+        self.base_url = base_url
+
+
+class UnsupportedMethodError(InternalCoreException):
+    """
+    Raised when a client is asked for an HTTP method it does not implement.
+    """
+
+    def __init__(self, method: HTTPMethod) -> None:
+        super().__init__(
+            message=f"Method {method} is not supported",
+            retryable=Retryability.NON_RETRYABLE,
+        )
+        self.method = method

corekit/http/response.py

@@ -1,12 +1,61 @@
 from pydantic import BaseModel, Field
 
+from corekit.exceptions import CoreHTTPException
+from corekit.http.exceptions import (
+    BadGatewayException,
+    ConflictErrorException,
+    ForbiddenException,
+    GatewayTimeoutException,
+    InternalServerErrorException,
+    NotFoundException,
+    ServiceUnavailableException,
+    TooManyRequestsException,
+    UnauthorizedException,
+    UnprocessableEntityException,
+)
+from corekit.http.status import HTTPStatusCode
 from corekit.schemas.pydantic.fields import DefaultDictField
 from corekit.schemas.types import AnyDict
 
 
 class BaseApiResponse(BaseModel):
-    status_code: int = Field(..., description="HTTP status code")
+    status_code: HTTPStatusCode | int = Field(..., description="HTTP status code")
     text: str = Field(..., description="Response text")
     data: AnyDict = DefaultDictField()
     headers: AnyDict = DefaultDictField()
     cookies: AnyDict = DefaultDictField()
+
+    @property
+    def ok(self) -> bool:
+        """
+        Whether the status is below 400. A failure is still a response.
+        """
+        return int(self.status_code) < 400
+
+    def raise_for_status(self) -> "BaseApiResponse":
+        """
+        Raise a typed HTTP exception for a failure status.
+
+        Opt-in. ``request`` still returns the failure so existing callers that
+        read ``status_code`` keep working.
+        """
+        if self.ok:
+            return self
+
+        typed = {
+            int(UnauthorizedException.code): UnauthorizedException,
+            int(ForbiddenException.code): ForbiddenException,
+            int(NotFoundException.code): NotFoundException,
+            int(ConflictErrorException.code): ConflictErrorException,
+            int(UnprocessableEntityException.code): UnprocessableEntityException,
+            int(TooManyRequestsException.code): TooManyRequestsException,
+            int(InternalServerErrorException.code): InternalServerErrorException,
+            int(BadGatewayException.code): BadGatewayException,
+            int(ServiceUnavailableException.code): ServiceUnavailableException,
+            int(GatewayTimeoutException.code): GatewayTimeoutException,
+        }
+        detail = self.text or f"HTTP {int(self.status_code)}"
+        exception_type = typed.get(int(self.status_code))
+        if exception_type is None:
+            raise CoreHTTPException(status_code=int(self.status_code), detail=detail)
+        raise exception_type(detail=detail)

corekit/http/status.py

@@ -0,0 +1,89 @@
+"""
+HTTP codes
+See HTTP Status Code Registry:
+https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
+
+And RFC 2324 - https://tools.ietf.org/html/rfc2324
+"""
+
+from corekit.schemas import IntegerEnum
+
+__all__ = ["HTTPStatusCode"]
+
+
+class HTTPStatusCode(IntegerEnum):
+    CONTINUE = 100
+    SWITCHING_PROTOCOLS = 101
+    PROCESSING = 102
+    EARLY_HINTS = 103
+    OK = 200
+    CREATED = 201
+    ACCEPTED = 202
+    NON_AUTHORITATIVE_INFORMATION = 203
+    NO_CONTENT = 204
+    RESET_CONTENT = 205
+    PARTIAL_CONTENT = 206
+    MULTI_STATUS = 207
+    ALREADY_REPORTED = 208
+    IM_USED = 226
+    MULTIPLE_CHOICES = 300
+    MOVED_PERMANENTLY = 301
+    FOUND = 302
+    SEE_OTHER = 303
+    NOT_MODIFIED = 304
+    USE_PROXY = 305
+    RESERVED = 306
+    TEMPORARY_REDIRECT = 307
+    PERMANENT_REDIRECT = 308
+    BAD_REQUEST = 400
+    UNAUTHORIZED = 401
+    PAYMENT_REQUIRED = 402
+    FORBIDDEN = 403
+    NOT_FOUND = 404
+    METHOD_NOT_ALLOWED = 405
+    NOT_ACCEPTABLE = 406
+    PROXY_AUTHENTICATION_REQUIRED = 407
+    REQUEST_TIMEOUT = 408
+    CONFLICT = 409
+    GONE = 410
+    LENGTH_REQUIRED = 411
+    PRECONDITION_FAILED = 412
+    REQUEST_ENTITY_TOO_LARGE = 413
+    REQUEST_URI_TOO_LONG = 414
+    UNSUPPORTED_MEDIA_TYPE = 415
+    REQUESTED_RANGE_NOT_SATISFIABLE = 416
+    EXPECTATION_FAILED = 417
+    IM_A_TEAPOT = 418
+    MISDIRECTED_REQUEST = 421
+    UNPROCESSABLE_ENTITY = 422
+    LOCKED = 423
+    FAILED_DEPENDENCY = 424
+    TOO_EARLY = 425
+    UPGRADE_REQUIRED = 426
+    PRECONDITION_REQUIRED = 428
+    TOO_MANY_REQUESTS = 429
+    REQUEST_HEADER_FIELDS_TOO_LARGE = 431
+    UNAVAILABLE_FOR_LEGAL_REASONS = 451
+    INTERNAL_SERVER_ERROR = 500
+    NOT_IMPLEMENTED = 501
+    BAD_GATEWAY = 502
+    SERVICE_UNAVAILABLE = 503
+    GATEWAY_TIMEOUT = 504
+    HTTP_VERSION_NOT_SUPPORTED = 505
+    VARIANT_ALSO_NEGOTIATES = 506
+    INSUFFICIENT_STORAGE = 507
+    LOOP_DETECTED = 508
+    NOT_EXTENDED = 510
+    NETWORK_AUTHENTICATION_REQUIRED = 511
+
+    @classmethod
+    def coerce(cls, code: int) -> "HTTPStatusCode | int":
+        """
+        Return the enum member for a known status, or the raw code otherwise.
+
+        Proxies and CDNs emit statuses this registry does not name. Callers
+        should still get the numeric code rather than a failed response parse.
+        """
+        if cls.is_member(code):
+            return cls.from_int(code)
+        return code

corekit/jobs/runner.py

@@ -13,6 +13,8 @@ Enqueueing a bound method makes the queue serialize the instance, which is the
 thing worth avoiding.
 """
 
+import asyncio
+import inspect
 import logging
 from typing import Any
 
@@ -31,6 +33,9 @@ def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
     ``success`` runs after ``task_function`` returns; ``failure`` runs if it
     raises, and the original exception is re-raised so the queue records the
     job as failed. A hook that raises does not mask the original error.
+    ``last_result`` and ``last_error`` are set on the task before the hook
+    runs. A coroutine ``task_function`` is awaited. ``timeout`` is not applied
+    here; the scheduling adapter owns that.
 
     Args:
         task_name: The registered name of the task to run.
@@ -48,10 +53,16 @@ def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
 
     try:
         result = task.task_function(*args, **kwargs)
-    except Exception:
+        if inspect.iscoroutine(result):
+            result = asyncio.run(result)
+    except Exception as exc:
+        task.last_result = None
+        task.last_error = exc
         _run_hook(task, "failure", args, kwargs)
         raise
 
+    task.last_result = result
+    task.last_error = None
     _run_hook(task, "success", args, kwargs)
     return result
 

corekit/jobs/task.py

@@ -88,6 +88,8 @@ class Task(abc.ABC):
         """
         self.name = name or self.task_name or type(self).__name__
         self.logger = logging.getLogger(type(self).__module__)
+        self.last_result: Any = None
+        self.last_error: BaseException | None = None
 
     @abc.abstractmethod
     def task_function(self, *args: Any, **kwargs: Any) -> None:
@@ -99,12 +101,18 @@ class Task(abc.ABC):
     def success(self, *args: Any, **kwargs: Any) -> None:
         """
         Called after ``task_function`` returns. Override to add behaviour.
+
+        ``last_result`` is set before this runs. The call signature stays
+        ``(*args, **kwargs)`` so an existing override is not broken.
         """
         self.logger.info(f"Task {self.name} completed successfully")
 
     def failure(self, *args: Any, **kwargs: Any) -> None:
         """
         Called when ``task_function`` raises. Override to add behaviour.
+
+        ``last_error`` is set before this runs. The call signature stays
+        ``(*args, **kwargs)`` so an existing override is not broken.
         """
         self.logger.error(f"Task {self.name} failed")
 
@@ -119,8 +127,11 @@ class ScheduledTask(Task):
     """
     A task that runs on a schedule.
 
-    The timing attributes are read by whichever adapter schedules the task;
-    nothing here talks to a scheduler itself.
+    ``interval``, ``repeat``, ``timeout``, and ``schedule_delay`` are for the
+    adapter that talks to a scheduler. ``run_task`` does not apply ``timeout``
+    and does not sleep for ``interval`` — wrapping a still-running queue job
+    would change production workers. Copy ``schedule_delay`` per instance so
+    one task cannot mutate the shared class dict.
     """
 
     interval: int | None = None
@@ -133,6 +144,16 @@ class ScheduledTask(Task):
     args: list[Any] | None = None
     kwargs: dict[str, Any] | None = None
 
+    def __init__(self, name: str | None = None) -> None:
+        super().__init__(name)
+        # Class attributes are shared. Replace them on the instance so a later
+        # in-place edit cannot change every other scheduled task.
+        self.schedule_delay = dict(self.schedule_delay)
+        if self.args is not None:
+            self.args = list(self.args)
+        if self.kwargs is not None:
+            self.kwargs = dict(self.kwargs)
+
     def get_start_time(self) -> datetime:
         """
         When the first run should happen.

corekit/log_monitor/models.py

@@ -75,10 +75,16 @@ class PauseContainerAction(BaseAction):
 
 
 class ExecuteCommandAction(BaseAction):
-    """Execute a shell command"""
+    """
+    Run a command as an argument list.
+
+    ``command`` is split like a shell command line, then ``{container}`` is
+    filled in. It is not passed to a shell, so pipes and redirects are not
+    available.
+    """
 
     type: Literal[ActionType.EXECUTE_COMMAND] = ActionType.EXECUTE_COMMAND
-    command: str = Field(..., description="Command template with {container} placeholder")
+    command: str = Field(..., description="Argument list template with a {container} placeholder")
 
 
 # Union type for all actions