queueflow 0.1.0__py3-none-any.whl

queueflow/exceptions.py

@@ -0,0 +1,199 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+from typing import Any, Optional
+from typing_extensions import Self
+
+class OpenApiException(Exception):
+    """The base exception class for all OpenAPIExceptions"""
+
+
+class ApiTypeError(OpenApiException, TypeError):
+    def __init__(self, msg, path_to_item=None, valid_classes=None,
+                 key_type=None) -> None:
+        """ Raises an exception for TypeErrors
+
+        Args:
+            msg (str): the exception message
+
+        Keyword Args:
+            path_to_item (list): a list of keys an indices to get to the
+                                 current_item
+                                 None if unset
+            valid_classes (tuple): the primitive classes that current item
+                                   should be an instance of
+                                   None if unset
+            key_type (bool): False if our value is a value in a dict
+                             True if it is a key in a dict
+                             False if our item is an item in a list
+                             None if unset
+        """
+        self.path_to_item = path_to_item
+        self.valid_classes = valid_classes
+        self.key_type = key_type
+        full_msg = msg
+        if path_to_item:
+            full_msg = "{0} at {1}".format(msg, render_path(path_to_item))
+        super(ApiTypeError, self).__init__(full_msg)
+
+
+class ApiValueError(OpenApiException, ValueError):
+    def __init__(self, msg, path_to_item=None) -> None:
+        """
+        Args:
+            msg (str): the exception message
+
+        Keyword Args:
+            path_to_item (list) the path to the exception in the
+                received_data dict. None if unset
+        """
+
+        self.path_to_item = path_to_item
+        full_msg = msg
+        if path_to_item:
+            full_msg = "{0} at {1}".format(msg, render_path(path_to_item))
+        super(ApiValueError, self).__init__(full_msg)
+
+
+class ApiAttributeError(OpenApiException, AttributeError):
+    def __init__(self, msg, path_to_item=None) -> None:
+        """
+        Raised when an attribute reference or assignment fails.
+
+        Args:
+            msg (str): the exception message
+
+        Keyword Args:
+            path_to_item (None/list) the path to the exception in the
+                received_data dict
+        """
+        self.path_to_item = path_to_item
+        full_msg = msg
+        if path_to_item:
+            full_msg = "{0} at {1}".format(msg, render_path(path_to_item))
+        super(ApiAttributeError, self).__init__(full_msg)
+
+
+class ApiKeyError(OpenApiException, KeyError):
+    def __init__(self, msg, path_to_item=None) -> None:
+        """
+        Args:
+            msg (str): the exception message
+
+        Keyword Args:
+            path_to_item (None/list) the path to the exception in the
+                received_data dict
+        """
+        self.path_to_item = path_to_item
+        full_msg = msg
+        if path_to_item:
+            full_msg = "{0} at {1}".format(msg, render_path(path_to_item))
+        super(ApiKeyError, self).__init__(full_msg)
+
+
+class ApiException(OpenApiException):
+
+    def __init__(
+        self, 
+        status=None, 
+        reason=None, 
+        http_resp=None,
+        *,
+        body: Optional[str] = None,
+        data: Optional[Any] = None,
+    ) -> None:
+        self.status = status
+        self.reason = reason
+        self.body = body
+        self.data = data
+        self.headers = None
+
+        if http_resp:
+            if self.status is None:
+                self.status = http_resp.status
+            if self.reason is None:
+                self.reason = http_resp.reason
+            if self.body is None:
+                try:
+                    self.body = http_resp.data.decode('utf-8')
+                except Exception:
+                    pass
+            self.headers = http_resp.getheaders()
+
+    @classmethod
+    def from_response(
+        cls, 
+        *, 
+        http_resp, 
+        body: Optional[str], 
+        data: Optional[Any],
+    ) -> Self:
+        if http_resp.status == 400:
+            raise BadRequestException(http_resp=http_resp, body=body, data=data)
+
+        if http_resp.status == 401:
+            raise UnauthorizedException(http_resp=http_resp, body=body, data=data)
+
+        if http_resp.status == 403:
+            raise ForbiddenException(http_resp=http_resp, body=body, data=data)
+
+        if http_resp.status == 404:
+            raise NotFoundException(http_resp=http_resp, body=body, data=data)
+
+        if 500 <= http_resp.status <= 599:
+            raise ServiceException(http_resp=http_resp, body=body, data=data)
+        raise ApiException(http_resp=http_resp, body=body, data=data)
+
+    def __str__(self):
+        """Custom error messages for exception"""
+        error_message = "({0})\n"\
+                        "Reason: {1}\n".format(self.status, self.reason)
+        if self.headers:
+            error_message += "HTTP response headers: {0}\n".format(
+                self.headers)
+
+        if self.data or self.body:
+            error_message += "HTTP response body: {0}\n".format(self.data or self.body)
+
+        return error_message
+
+
+class BadRequestException(ApiException):
+    pass
+
+
+class NotFoundException(ApiException):
+    pass
+
+
+class UnauthorizedException(ApiException):
+    pass
+
+
+class ForbiddenException(ApiException):
+    pass
+
+
+class ServiceException(ApiException):
+    pass
+
+
+def render_path(path_to_item):
+    """Returns a string representation of a path"""
+    result = ""
+    for pth in path_to_item:
+        if isinstance(pth, int):
+            result += "[{0}]".format(pth)
+        else:
+            result += "['{0}']".format(pth)
+    return result

queueflow/facade.py

@@ -0,0 +1,255 @@
+"""Ergonomic facade for the QueueFlow Python SDK.
+
+Hand-written ergonomics layered on the GENERATED core (api clients + models).
+Injected at generation time as a supporting file, so it ships with the
+generated package but is never produced by the raw codegen. The wire types and
+the per-tag api clients come from the generated modules and are never edited.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+from .api_client import ApiClient
+from .configuration import Configuration
+from .api.jobs_api import JobsApi
+from .api.workflows_api import WorkflowsApi
+from .api.worker_api import WorkerApi
+from .api.system_api import SystemApi
+from .api.health_api import HealthApi
+from .api.cron_api import CronApi
+from .api.dlq_api import DlqApi
+from .models.create_job_request import CreateJobRequest
+from .models.job_config_request import JobConfigRequest
+from .models.create_workflow_request import CreateWorkflowRequest
+from .models.create_cron_request import CreateCronRequest
+from .models.workflow_step import WorkflowStep
+from .models.job import Job
+from .models.workflow import Workflow
+
+_TERMINAL_JOB = {"completed", "failed", "cancelled"}
+_TERMINAL_WORKFLOW = {"completed", "failed", "partially_failed", "cancelled"}
+
+
+class WaitTimeout(TimeoutError):
+    """Raised when wait_for_* exceeds its deadline."""
+
+
+class WorkflowValidationError(ValueError):
+    """Raised by WorkflowBuilder.build() for a structurally invalid DAG."""
+
+
+class QueueFlow:
+    """Ergonomic client wrapping the generated api clients.
+
+    qf = QueueFlow("http://localhost:8000", "dev")
+    job = qf.create_job("echo", payload={"hi": 1})
+    done = qf.wait_for_job(job.id)
+
+    The worker-protocol routes (``qf.worker``: lease, heartbeat, complete,
+    fail) authenticate with the server's *worker token*, not a tenant token.
+    Pass it as ``worker_token=``; without it, ``qf.worker`` reuses the tenant
+    token, which only works in the server's development mode.
+    """
+
+    def __init__(self, base_url: str, token: str, worker_token: Optional[str] = None) -> None:
+        config = Configuration(host=base_url.rstrip("/"))
+        config.access_token = token
+        self._client = ApiClient(config)
+        self.jobs = JobsApi(self._client)
+        self.workflows = WorkflowsApi(self._client)
+        if worker_token is not None:
+            worker_config = Configuration(host=base_url.rstrip("/"))
+            worker_config.access_token = worker_token
+            self._worker_client: Optional[ApiClient] = ApiClient(worker_config)
+            self.worker = WorkerApi(self._worker_client)
+        else:
+            self._worker_client = None
+            self.worker = WorkerApi(self._client)
+        self.cron = CronApi(self._client)
+        self.dlq = DlqApi(self._client)
+        self.system = SystemApi(self._client)
+        self.health_api = HealthApi(self._client)
+
+    # --- jobs ---------------------------------------------------------------
+
+    def create_job(
+        self,
+        task: str,
+        payload: Optional[Dict[str, Any]] = None,
+        priority: Optional[int] = None,
+        max_retries: Optional[int] = None,
+        timeout: Optional[int] = None,
+        queue: Optional[str] = None,
+        retry_backoff: Optional[str] = None,
+        retry_delay_secs: Optional[int] = None,
+        retry_max_delay_secs: Optional[int] = None,
+        jitter_factor: Optional[float] = None,
+        idempotency_key: Optional[str] = None,
+        run_at: Optional[Any] = None,
+    ) -> Job:
+        """Enqueue a job and return its freshly-created record.
+
+        run_at (a datetime) delays the first run: the job is created
+        immediately but stays invisible to workers until then.
+        """
+        config = None
+        overrides = (
+            priority, max_retries, timeout, queue,
+            retry_backoff, retry_delay_secs, retry_max_delay_secs, jitter_factor,
+        )
+        if any(v is not None for v in overrides):
+            config = JobConfigRequest(
+                priority=priority,
+                max_retries=max_retries,
+                timeout=timeout,
+                queue=queue,
+                retry_backoff=retry_backoff,
+                retry_delay_secs=retry_delay_secs,
+                retry_max_delay_secs=retry_max_delay_secs,
+                jitter_factor=jitter_factor,
+            )
+        req = CreateJobRequest(task_name=task, payload=payload or {}, config=config, run_at=run_at)
+        created = self.jobs.create_job(req, idempotency_key=idempotency_key)
+        return self.jobs.get_job(created.job_id)
+
+    def wait_for_job(self, job_id: str, timeout: float = 60.0, interval: float = 0.5) -> Job:
+        """Poll until the job reaches a terminal state (completed/failed/cancelled)."""
+        return self._poll(lambda: self.jobs.get_job(job_id), _TERMINAL_JOB, job_id, "job", timeout, interval)
+
+    # --- workflows ----------------------------------------------------------
+
+    def create_workflow(self, workflow: "WorkflowBuilder | CreateWorkflowRequest") -> Workflow:
+        body = workflow.build() if isinstance(workflow, WorkflowBuilder) else workflow
+        created = self.workflows.create_workflow(body)
+        return self.workflows.get_workflow(created.workflow_id)
+
+    def wait_for_workflow(self, workflow_id: str, timeout: float = 60.0, interval: float = 0.5) -> Workflow:
+        return self._poll(
+            lambda: self.workflows.get_workflow(workflow_id),
+            _TERMINAL_WORKFLOW,
+            workflow_id,
+            "workflow",
+            timeout,
+            interval,
+        )
+
+    # --- cron & dead letters ------------------------------------------------
+
+    def create_cron(
+        self,
+        name: str,
+        schedule: str,
+        task: str,
+        payload: Optional[Dict[str, Any]] = None,
+        queue: Optional[str] = None,
+    ) -> str:
+        """Register a recurring enqueue (5-field crontab, UTC); returns the schedule id."""
+        req = CreateCronRequest(
+            name=name, cron_expr=schedule, task_name=task, payload=payload or {}, queue=queue
+        )
+        return self.cron.create_cron(req).cron_id
+
+    def replay_dead_letter(self, dead_letter_id: int) -> Job:
+        """Re-run a dead-lettered job as a fresh job; returns the new job record.
+
+        Each entry replays at most once (a second replay is a 409).
+        """
+        replayed = self.dlq.replay_dead_letter(dead_letter_id)
+        return self.jobs.get_job(replayed.job_id)
+
+    # --- internal -----------------------------------------------------------
+
+    @staticmethod
+    def _poll(fetch, terminal, rid, kind, timeout, interval):
+        deadline = time.monotonic() + timeout
+        while True:
+            value = fetch()
+            if value.status in terminal:
+                return value
+            if time.monotonic() + interval > deadline:
+                raise WaitTimeout(kind + " " + rid + " did not finish within " + str(timeout) + "s")
+            time.sleep(interval)
+
+
+class WorkflowBuilder:
+    """Typed builder for a workflow DAG, with local validation before the round-trip."""
+
+    def __init__(self, name: str) -> None:
+        if not name:
+            raise WorkflowValidationError("workflow name is required")
+        self.name = name
+        self._steps: List[WorkflowStep] = []
+        self._context: Dict[str, Any] = {}
+        self._metadata: Dict[str, Any] = {}
+
+    def step(
+        self,
+        name: str,
+        task: str,
+        after: Optional[List[str]] = None,
+        payload: Optional[Dict[str, Any]] = None,
+        on_failure: Optional[str] = None,
+        on_success: Optional[str] = None,
+        config: Optional[Any] = None,
+    ) -> "WorkflowBuilder":
+        """Add a step. config is a models.JobConfig override for this step;
+        the server fills defaults for any field left unset."""
+        self._steps.append(
+            WorkflowStep(
+                name=name,
+                task_name=task,
+                depends_on=after or [],
+                payload=payload or {},
+                on_failure=on_failure,
+                on_success=on_success,
+                config=config,
+            )
+        )
+        return self
+
+    def context(self, **kwargs: Any) -> "WorkflowBuilder":
+        self._context.update(kwargs)
+        return self
+
+    def build(self) -> CreateWorkflowRequest:
+        if not self._steps:
+            raise WorkflowValidationError('workflow "' + self.name + '" has no steps')
+        names = set()
+        for s in self._steps:
+            if s.name in names:
+                raise WorkflowValidationError('duplicate step name "' + s.name + '"')
+            names.add(s.name)
+        for s in self._steps:
+            for dep in (s.depends_on or []):
+                if dep not in names:
+                    raise WorkflowValidationError('step "' + s.name + '" depends on unknown step "' + dep + '"')
+        self._assert_acyclic()
+        return CreateWorkflowRequest(
+            name=self.name, steps=self._steps, context=self._context, metadata=self._metadata
+        )
+
+    def _assert_acyclic(self) -> None:
+        by_name = {s.name: s for s in self._steps}
+        visiting, done = set(), set()
+
+        def visit(node: str, stack: List[str]) -> None:
+            if node in done:
+                return
+            if node in visiting:
+                cycle = " -> ".join(stack[stack.index(node):] + [node])
+                raise WorkflowValidationError("dependency cycle: " + cycle)
+            visiting.add(node)
+            for dep in (by_name[node].depends_on or []):
+                visit(dep, stack + [node])
+            visiting.discard(node)
+            done.add(node)
+
+        for s in self._steps:
+            visit(s.name, [])
+
+
+def wf(name: str) -> WorkflowBuilder:
+    """Shorthand for WorkflowBuilder(name)."""
+    return WorkflowBuilder(name)

queueflow/models/__init__.py

@@ -0,0 +1,57 @@
+# coding: utf-8
+
+# flake8: noqa
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+# import models into model package
+from queueflow.models.backoff_strategy import BackoffStrategy
+from queueflow.models.complete_job_request import CompleteJobRequest
+from queueflow.models.create_batch_jobs_request import CreateBatchJobsRequest
+from queueflow.models.create_batch_jobs_response import CreateBatchJobsResponse
+from queueflow.models.create_cron_request import CreateCronRequest
+from queueflow.models.create_cron_response import CreateCronResponse
+from queueflow.models.create_job_request import CreateJobRequest
+from queueflow.models.create_job_response import CreateJobResponse
+from queueflow.models.create_workflow_request import CreateWorkflowRequest
+from queueflow.models.create_workflow_response import CreateWorkflowResponse
+from queueflow.models.cron_schedule import CronSchedule
+from queueflow.models.dead_letter import DeadLetter
+from queueflow.models.error_body import ErrorBody
+from queueflow.models.fail_job_request import FailJobRequest
+from queueflow.models.health_status import HealthStatus
+from queueflow.models.heartbeat_request import HeartbeatRequest
+from queueflow.models.heartbeat_response import HeartbeatResponse
+from queueflow.models.job import Job
+from queueflow.models.job_config import JobConfig
+from queueflow.models.job_config_request import JobConfigRequest
+from queueflow.models.job_status import JobStatus
+from queueflow.models.lease_jobs_request import LeaseJobsRequest
+from queueflow.models.lease_jobs_response import LeaseJobsResponse
+from queueflow.models.leased_job import LeasedJob
+from queueflow.models.list_crons_response import ListCronsResponse
+from queueflow.models.list_dead_letters_response import ListDeadLettersResponse
+from queueflow.models.list_jobs_response import ListJobsResponse
+from queueflow.models.list_workflows_response import ListWorkflowsResponse
+from queueflow.models.on_failure import OnFailure
+from queueflow.models.on_success import OnSuccess
+from queueflow.models.ready_status import ReadyStatus
+from queueflow.models.replay_dead_letter_response import ReplayDeadLetterResponse
+from queueflow.models.stats_snapshot import StatsSnapshot
+from queueflow.models.step_status import StepStatus
+from queueflow.models.tasks_response import TasksResponse
+from queueflow.models.workflow import Workflow
+from queueflow.models.workflow_diagram_response import WorkflowDiagramResponse
+from queueflow.models.workflow_status import WorkflowStatus
+from queueflow.models.workflow_step import WorkflowStep
+from queueflow.models.workflow_step_state import WorkflowStepState
+from queueflow.models.workflow_step_states_response import WorkflowStepStatesResponse

queueflow/models/backoff_strategy.py

@@ -0,0 +1,38 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import json
+from enum import Enum
+from typing_extensions import Self
+
+
+class BackoffStrategy(str, Enum):
+    """
+    How retry delays grow between attempts.
+    """
+
+    """
+    allowed enum values
+    """
+    FIXED = 'fixed'
+    LINEAR = 'linear'
+    EXPONENTIAL = 'exponential'
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Self:
+        """Create an instance of BackoffStrategy from a JSON string"""
+        return cls(json.loads(json_str))
+
+

queueflow/models/complete_job_request.py

@@ -0,0 +1,89 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field, StrictStr
+from typing import Any, ClassVar, Dict, List, Optional
+from typing import Optional, Set
+from typing_extensions import Self
+
+class CompleteJobRequest(BaseModel):
+    """
+    Body for `POST /api/v1/jobs/{id}/complete`.
+    """ # noqa: E501
+    lease_token: StrictStr = Field(description="The lease token returned by the lease call.")
+    result: Optional[Dict[str, Any]] = Field(default=None, description="Handler result, recorded on the job and merged into workflow context.")
+    __properties: ClassVar[List[str]] = ["lease_token", "result"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of CompleteJobRequest from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of CompleteJobRequest from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "lease_token": obj.get("lease_token"),
+            "result": obj.get("result")
+        })
+        return _obj
+
+