dbos 0.27.0a11__py3-none-any.whl → 0.28.0a4__py3-none-any.whl

dbos/_client.py

@@ -6,6 +6,7 @@ from typing import Any, Generic, List, Optional, TypedDict, TypeVar
 from sqlalchemy import URL
 
 from dbos._app_db import ApplicationDatabase
+from dbos._context import MaxPriority, MinPriority
 
 if sys.version_info < (3, 11):
     from typing_extensions import NotRequired
@@ -15,7 +16,7 @@ else:
 from dbos import _serialization
 from dbos._dbos import WorkflowHandle, WorkflowHandleAsync
 from dbos._dbos_config import parse_database_url_to_dbconfig
-from dbos._error import DBOSNonExistentWorkflowError
+from dbos._error import DBOSException, DBOSNonExistentWorkflowError
 from dbos._registrations import DEFAULT_MAX_RECOVERY_ATTEMPTS
 from dbos._serialization import WorkflowInputs
 from dbos._sys_db import (
@@ -44,6 +45,15 @@ class EnqueueOptions(TypedDict):
     app_version: NotRequired[str]
     workflow_timeout: NotRequired[float]
     deduplication_id: NotRequired[str]
+    priority: NotRequired[int]
+
+
+def validate_enqueue_options(options: EnqueueOptions) -> None:
+    priority = options.get("priority")
+    if priority is not None and (priority < MinPriority or priority > MaxPriority):
+        raise DBOSException(
+            f"Invalid priority {priority}. Priority must be between {MinPriority}~{MaxPriority}."
+        )
 
 
 class WorkflowHandleClientPolling(Generic[R]):
@@ -103,6 +113,7 @@ class DBOSClient:
         self._sys_db.destroy()
 
     def _enqueue(self, options: EnqueueOptions, *args: Any, **kwargs: Any) -> str:
+        validate_enqueue_options(options)
         workflow_name = options["workflow_name"]
         queue_name = options["queue_name"]
 
@@ -116,6 +127,7 @@ class DBOSClient:
         workflow_timeout = options.get("workflow_timeout", None)
         enqueue_options_internal: EnqueueOptionsInternal = {
             "deduplication_id": options.get("deduplication_id"),
+            "priority": options.get("priority"),
         }
 
         status: WorkflowStatusInternal = {

dbos/_context.py

@@ -31,6 +31,9 @@ class OperationType(Enum):
 
 OperationTypes = Literal["handler", "workflow", "transaction", "step", "procedure"]
 
+MaxPriority = 2**31 - 1  # 2,147,483,647
+MinPriority = 1
+
 
 # Keys must be the same as in TypeScript Transact
 class TracedAttributes(TypedDict, total=False):
@@ -100,6 +103,8 @@ class DBOSContext:
 
         # A user-specified deduplication ID for the enqueuing workflow.
         self.deduplication_id: Optional[str] = None
+        # A user-specified priority for the enqueuing workflow.
+        self.priority: Optional[int] = None
 
     def create_child(self) -> DBOSContext:
         rv = DBOSContext()
@@ -422,15 +427,23 @@ class SetEnqueueOptions:
 
     Usage:
         ```
-        with SetEnqueueOptions(deduplication_id=<deduplication id>):
+        with SetEnqueueOptions(deduplication_id=<deduplication id>, priority=<priority>):
             queue.enqueue(...)
         ```
     """
 
-    def __init__(self, *, deduplication_id: Optional[str] = None) -> None:
+    def __init__(
+        self, *, deduplication_id: Optional[str] = None, priority: Optional[int] = None
+    ) -> None:
         self.created_ctx = False
         self.deduplication_id: Optional[str] = deduplication_id
         self.saved_deduplication_id: Optional[str] = None
+        if priority is not None and (priority < MinPriority or priority > MaxPriority):
+            raise Exception(
+                f"Invalid priority {priority}. Priority must be between {MinPriority}~{MaxPriority}."
+            )
+        self.priority: Optional[int] = priority
+        self.saved_priority: Optional[int] = None
 
     def __enter__(self) -> SetEnqueueOptions:
         # Code to create a basic context
@@ -441,6 +454,8 @@ class SetEnqueueOptions:
         ctx = assert_current_dbos_context()
         self.saved_deduplication_id = ctx.deduplication_id
         ctx.deduplication_id = self.deduplication_id
+        self.saved_priority = ctx.priority
+        ctx.priority = self.priority
         return self
 
     def __exit__(
@@ -449,7 +464,9 @@ class SetEnqueueOptions:
         exc_value: Optional[BaseException],
         traceback: Optional[TracebackType],
     ) -> Literal[False]:
-        assert_current_dbos_context().deduplication_id = self.saved_deduplication_id
+        curr_ctx = assert_current_dbos_context()
+        curr_ctx.deduplication_id = self.saved_deduplication_id
+        curr_ctx.priority = self.saved_priority
         # Code to clean up the basic context if we created it
         if self.created_ctx:
             _clear_local_dbos_context()
@@ -463,6 +480,7 @@ class EnterDBOSWorkflow(AbstractContextManager[DBOSContext, Literal[False]]):
         self.is_temp_workflow = attributes["name"] == "temp_wf"
         self.saved_workflow_timeout: Optional[int] = None
         self.saved_deduplication_id: Optional[str] = None
+        self.saved_priority: Optional[int] = None
 
     def __enter__(self) -> DBOSContext:
         # Code to create a basic context
@@ -476,10 +494,12 @@ class EnterDBOSWorkflow(AbstractContextManager[DBOSContext, Literal[False]]):
         # workflow's children (instead we propagate the deadline)
         self.saved_workflow_timeout = ctx.workflow_timeout_ms
         ctx.workflow_timeout_ms = None
-        # Unset the deduplication_id context var so it is not applied to this
+        # Unset the deduplication_id and priority context var so it is not applied to this
         # workflow's children
         self.saved_deduplication_id = ctx.deduplication_id
         ctx.deduplication_id = None
+        self.saved_priority = ctx.priority
+        ctx.priority = None
         ctx.start_workflow(
             None, self.attributes, self.is_temp_workflow
         )  # Will get from the context's next workflow ID
@@ -498,7 +518,8 @@ class EnterDBOSWorkflow(AbstractContextManager[DBOSContext, Literal[False]]):
         ctx.workflow_timeout_ms = self.saved_workflow_timeout
         # Clear any propagating timeout
         ctx.workflow_deadline_epoch_ms = None
-        # Restore the saved deduplication ID
+        # Restore the saved deduplication ID and priority
+        ctx.priority = self.saved_priority
         ctx.deduplication_id = self.saved_deduplication_id
         # Code to clean up the basic context if we created it
         if self.created_ctx:

dbos/_core.py

@@ -544,6 +544,7 @@ def start_workflow(
     )
     enqueue_options = EnqueueOptionsInternal(
         deduplication_id=local_ctx.deduplication_id if local_ctx is not None else None,
+        priority=local_ctx.priority if local_ctx is not None else None,
     )
     new_wf_id, new_wf_ctx = _get_new_wf()
 
@@ -635,6 +636,7 @@ async def start_workflow_async(
     )
     enqueue_options = EnqueueOptionsInternal(
         deduplication_id=local_ctx.deduplication_id if local_ctx is not None else None,
+        priority=local_ctx.priority if local_ctx is not None else None,
     )
     new_wf_id, new_wf_ctx = _get_new_wf()
 

dbos/_dbos.py

@@ -371,7 +371,7 @@ class DBOS:
         set_env_vars(self._config)
         config_logger(self._config)
         dbos_tracer.config(self._config)
-        dbos_logger.info("Initializing DBOS")
+        dbos_logger.info(f"Initializing DBOS (v{GlobalParams.dbos_version})")
 
         # If using FastAPI, set up middleware and lifecycle events
         if self.fastapi is not None:

dbos/_migrations/versions/933e86bdac6a_add_queue_priority.py

@@ -0,0 +1,35 @@
+"""add queue priority
+
+Revision ID: 933e86bdac6a
+Revises: 27ac6900c6ad
+Create Date: 2025-04-25 18:17:40.462737
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "933e86bdac6a"
+down_revision: Union[str, None] = "27ac6900c6ad"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "workflow_queue",
+        sa.Column(
+            "priority",
+            sa.Integer(),
+            nullable=False,
+            server_default=sa.text("'0'::int"),
+        ),
+        schema="dbos",
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("workflow_queue", "priority", schema="dbos")

dbos/_schemas/system_database.py

@@ -180,6 +180,12 @@ class SystemSchema:
             Text,
             nullable=True,
         ),
+        Column(
+            "priority",
+            Integer,
+            nullable=False,
+            server_default=text("'0'::int"),
+        ),
         UniqueConstraint(
             "queue_name", "deduplication_id", name="uq_workflow_queue_name_dedup_id"
         ),

dbos/_sys_db.py

@@ -138,6 +138,9 @@ class WorkflowStatusInternal(TypedDict):
 
 class EnqueueOptionsInternal(TypedDict):
     deduplication_id: Optional[str]  # Unique ID for deduplication on a queue
+    priority: Optional[
+        int
+    ]  # Priority of the workflow on the queue, starting from 1 ~ 2,147,483,647. Default 0 (highest priority).
 
 
 class RecordedResult(TypedDict):
@@ -1633,12 +1636,19 @@ class SystemDatabase:
                 if enqueue_options is not None
                 else None
             )
+            priority = (
+                enqueue_options["priority"] if enqueue_options is not None else None
+            )
+            # Default to 0 (highest priority) if not provided
+            if priority is None:
+                priority = 0
             query = (
                 pg.insert(SystemSchema.workflow_queue)
                 .values(
                     workflow_uuid=workflow_id,
                     queue_name=queue_name,
                     deduplication_id=deduplication_id,
+                    priority=priority,
                 )
                 .on_conflict_do_nothing(
                     index_elements=SystemSchema.workflow_queue.primary_key.columns
@@ -1747,7 +1757,10 @@ class SystemDatabase:
                 .where(SystemSchema.workflow_queue.c.queue_name == queue.name)
                 .where(SystemSchema.workflow_queue.c.started_at_epoch_ms == None)
                 .where(SystemSchema.workflow_queue.c.completed_at_epoch_ms == None)
-                .order_by(SystemSchema.workflow_queue.c.created_at_epoch_ms.asc())
+                .order_by(
+                    SystemSchema.workflow_queue.c.priority.asc(),
+                    SystemSchema.workflow_queue.c.created_at_epoch_ms.asc(),
+                )
                 .with_for_update(nowait=True)  # Error out early
             )
             # Apply limit only if max_tasks is finite

dbos/_utils.py

@@ -1,3 +1,4 @@
+import importlib.metadata
 import os
 
 INTERNAL_QUEUE_NAME = "_dbos_internal_queue"
@@ -6,3 +7,9 @@ INTERNAL_QUEUE_NAME = "_dbos_internal_queue"
 class GlobalParams:
     app_version: str = os.environ.get("DBOS__APPVERSION", "")
     executor_id: str = os.environ.get("DBOS__VMID", "local")
+    try:
+        # Only works on Python >= 3.8
+        dbos_version = importlib.metadata.version("dbos")
+    except importlib.metadata.PackageNotFoundError:
+        # If package is not installed or during development
+        dbos_version = "unknown"

dbos/cli/cli.py

@@ -24,6 +24,7 @@ from .._dbos_config import _is_valid_app_name
 from .._docker_pg_helper import start_docker_pg, stop_docker_pg
 from .._schemas.system_database import SystemSchema
 from .._sys_db import SystemDatabase, reset_system_database
+from .._utils import GlobalParams
 from ..cli._github_init import create_template_from_github
 from ._template_init import copy_template, get_project_name, get_templates_directory
 
@@ -42,6 +43,14 @@ def start_client(db_url: Optional[str] = None) -> DBOSClient:
 
 
 app = typer.Typer()
+
+
+@app.command(help="Show the version and exit")
+def version() -> None:
+    """Display the current version of DBOS CLI."""
+    typer.echo(f"DBOS CLI version: {GlobalParams.dbos_version}")
+
+
 workflow = typer.Typer()
 queue = typer.Typer()
 

dbos-0.28.0a4.dist-info/METADATA

@@ -0,0 +1,312 @@
+Metadata-Version: 2.1
+Name: dbos
+Version: 0.28.0a4
+Summary: Ultra-lightweight durable execution in Python
+Author-Email: "DBOS, Inc." <contact@dbos.dev>
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: alembic>=1.13.3
+Requires-Dist: typing-extensions>=4.12.2; python_version < "3.10"
+Requires-Dist: typer>=0.12.5
+Requires-Dist: jsonpickle>=3.3.0
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: fastapi[standard]>=0.115.2
+Requires-Dist: tomlkit>=0.13.2
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: docker>=7.1.0
+Requires-Dist: cryptography>=43.0.3
+Requires-Dist: rich>=13.9.4
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: websockets>=15.0
+Description-Content-Type: text/markdown
+
+
+<div align="center">
+
+# DBOS Transact: Lightweight Durable Workflows
+
+#### [Documentation](https://docs.dbos.dev/) &nbsp;&nbsp;•&nbsp;&nbsp;  [Examples](https://docs.dbos.dev/examples) &nbsp;&nbsp;•&nbsp;&nbsp; [Github](https://github.com/dbos-inc) &nbsp;&nbsp;•&nbsp;&nbsp; [Discord](https://discord.com/invite/jsmC6pXGgX)
+</div>
+
+---
+
+## What is DBOS?
+
+DBOS provides lightweight durable workflows built on top of Postgres.
+Instead of managing your own workflow orchestrator or task queue system, you can use DBOS to add durable workflows and queues to your program in just a few lines of code.
+
+To get started, follow the [quickstart](https://docs.dbos.dev/quickstart) to install this open-source library and connect it to a Postgres database.
+Then, annotate workflows and steps in your program to make it durable!
+That's all you need to do&mdash;DBOS is entirely contained in this open-source library, there's no additional infrastructure for you to configure or manage.
+
+## When Should I Use DBOS?
+
+You should consider using DBOS if your application needs to **reliably handle failures**.
+For example, you might be building a payments service that must reliably process transactions even if servers crash mid-operation, or a long-running data pipeline that needs to resume seamlessly from checkpoints rather than restart from the beginning when interrupted.
+
+Handling failures is costly and complicated, requiring complex state management and recovery logic as well as heavyweight tools like external orchestration services.
+DBOS makes it simpler: annotate your code to checkpoint it in Postgres and automatically recover from any failure.
+DBOS also provides powerful Postgres-backed primitives that makes it easier to write and operate reliable code, including durable queues, notifications, scheduling, event processing, and programmatic workflow management.
+
+## Features
+
+<details open><summary><strong>💾 Durable Workflows</strong></summary>
+
+####
+
+DBOS workflows make your program **durable** by checkpointing its state in Postgres.
+If your program ever fails, when it restarts all your workflows will automatically resume from the last completed step.
+
+You add durable workflows to your existing Python program by annotating ordinary functions as workflows and steps:
+
+```python
+from dbos import DBOS
+
+@DBOS.step()
+def step_one():
+    ...
+
+@DBOS.step()
+def step_two():
+    ...
+
+@DBOS.workflow()
+def workflow()
+    step_one()
+    step_two()
+```
+
+Workflows are particularly useful for 
+
+- Orchestrating business processes so they seamlessly recover from any failure.
+- Building observable and fault-tolerant data pipelines.
+- Operating an AI agent, or any application that relies on unreliable or non-deterministic APIs.
+
+[Read more ↗️](https://docs.dbos.dev/python/tutorials/workflow-tutorial)
+
+</details>
+
+<details><summary><strong>📒 Durable Queues</strong></summary>
+
+####
+
+DBOS queues help you **durably** run tasks in the background.
+You can enqueue a task (which can be a single step or an entire workflow) from a durable workflow and one of your processes will pick it up for execution.
+DBOS manages the execution of your tasks: it guarantees that tasks complete, and that their callers get their results without needing to resubmit them, even if your application is interrupted.
+
+Queues also provide flow control, so you can limit the concurrency of your tasks on a per-queue or per-process basis.
+You can also set timeouts for tasks, rate limit how often queued tasks are executed, deduplicate tasks, or prioritize tasks.
+
+You can add queues to your workflows in just a couple lines of code.
+They don't require a separate queueing service or message broker&mdash;just Postgres.
+
+```python
+from dbos import DBOS, Queue
+
+queue = Queue("example_queue")
+
+@DBOS.step()
+def process_task(task):
+  ...
+
+@DBOS.workflow()
+def process_tasks(tasks):
+  task_handles = []
+  # Enqueue each task so all tasks are processed concurrently.
+  for task in tasks:
+    handle = queue.enqueue(process_task, task)
+    task_handles.append(handle)
+  # Wait for each task to complete and retrieve its result.
+  # Return the results of all tasks.
+  return [handle.get_result() for handle in task_handles]
+```
+
+[Read more ↗️](https://docs.dbos.dev/python/tutorials/queue-tutorial)
+
+</details>
+
+<details><summary><strong>⚙️ Programmatic Workflow Management</strong></summary>
+
+####
+
+Your workflows are stored as rows in a Postgres table, so you have full programmatic control over them.
+Write scripts to query workflow executions, batch pause or resume workflows, or even restart failed workflows from a specific step.
+Handle bugs or failures that affect thousands of workflows with power and flexibility.
+
+```python
+# Create a DBOS client connected to your Postgres database.
+client = DBOSClient(database_url)
+# Find all workflows that errored between 3:00 and 5:00 AM UTC on 2025-04-22.
+workflows = client.list_workflows(status="ERROR", 
+  start_time="2025-04-22T03:00:00Z", end_time="2025-04-22T05:00:00Z")
+for workflow in workflows:
+    # Check which workflows failed due to an outage in a service called from Step 2.
+    steps = client.list_workflow_steps(workflow)
+    if len(steps) >= 3 and isinstance(steps[2]["error"], ServiceOutage):
+        # To recover from the outage, restart those workflows from Step 2.
+        DBOS.fork_workflow(workflow.workflow_id, 2)
+```
+
+[Read more ↗️](https://docs.dbos.dev/python/reference/client)
+
+</details>
+
+<details><summary><strong>🎫 Exactly-Once Event Processing</strong></summary>
+
+####
+
+Use DBOS to build reliable webhooks, event listeners, or Kafka consumers by starting a workflow exactly-once in response to an event.
+Acknowledge the event immediately while reliably processing it in the background.
+
+For example:
+
+```python
+def handle_message(request: Request) -> None:
+  event_id = request.body["event_id"]
+  # Use the event ID as an idempotency key to start the workflow exactly-once
+  with SetWorkflowID(event_id):
+    # Start the workflow in the background, then acknowledge the event
+    DBOS.start_workflow(message_workflow, request.body["event"])
+```
+
+Or with Kafka:
+
+```python
+@DBOS.kafka_consumer(config,["alerts-topic"])
+@DBOS.workflow()
+def process_kafka_alerts(msg):
+    # This workflow runs exactly-once for each message sent to the topic
+    alerts = msg.value.decode()
+    for alert in alerts:
+        respond_to_alert(alert)
+```
+
+[Read more ↗️](https://docs.dbos.dev/python/tutorials/workflow-tutorial)
+
+</details>
+
+<details><summary><strong>📅 Durable Scheduling</strong></summary>
+
+####
+
+Schedule workflows using cron syntax, or use durable sleep to pause workflows for as long as you like (even days or weeks) before executing.
+
+You can schedule a workflow using a single annotation:
+
+```python
+@DBOS.scheduled('* * * * *') # crontab syntax to run once every minute
+@DBOS.workflow()
+def example_scheduled_workflow(scheduled_time: datetime, actual_time: datetime):
+    DBOS.logger.info("I am a workflow scheduled to run once a minute.")
+```
+
+You can add a durable sleep to any workflow with a single line of code.
+It stores its wakeup time in Postgres so the workflow sleeps through any interruption or restart, then always resumes on schedule.
+
+```python
+@DBOS.workflow()
+def reminder_workflow(email: str, time_to_sleep: int):
+    send_confirmation_email(email)
+    DBOS.sleep(time_to_sleep)
+    send_reminder_email(email)
+```
+
+[Read more ↗️](https://docs.dbos.dev/python/tutorials/scheduled-workflows)
+
+</details>
+
+<details><summary><strong>📫 Durable Notifications</strong></summary>
+
+####
+
+Pause your workflow executions until a notification is received, or emit events from your workflow to send progress updates to external clients.
+All notifications are stored in Postgres, so they can be sent and received with exactly-once semantics.
+Set durable timeouts when waiting for events, so you can wait for as long as you like (even days or weeks) through interruptions or restarts, then resume once a notification arrives or the timeout is reached.
+
+For example, build a reliable billing workflow that durably waits for a notification from a payments service, processing it exactly-once:
+
+```python
+@DBOS.workflow()
+def billing_workflow():
+  ... # Calculate the charge, then submit the bill to a payments service
+  payment_status = DBOS.recv(PAYMENT_STATUS, timeout=payment_service_timeout)
+  if payment_status is not None and payment_status == "paid":
+      ... # Handle a successful payment.
+  else:
+      ... # Handle a failed payment or timeout.
+```
+
+</details>
+
+
+## Getting Started
+
+To get started, follow the [quickstart](https://docs.dbos.dev/quickstart) to install this open-source library and connect it to a Postgres database.
+Then, check out the [programming guide](https://docs.dbos.dev/python/programming-guide) to learn how to build with durable workflows and queues.
+
+## Documentation
+
+[https://docs.dbos.dev](https://docs.dbos.dev)
+
+## Examples
+
+[https://docs.dbos.dev/examples](https://docs.dbos.dev/examples)
+
+## DBOS vs. Other Systems
+
+<details><summary><strong>DBOS vs. Temporal</strong></summary>
+
+####
+
+Both DBOS and Temporal provide durable execution, but DBOS is implemented in a lightweight Postgres-backed library whereas Temporal is implemented in an externally orchestrated server.
+
+You can add DBOS to your program by installing this open-source library, connecting it to Postgres, and annotating workflows and steps.
+By contrast, to add Temporal to your program, you must rearchitect your program to move your workflows and steps (activities) to a Temporal worker, configure a Temporal server to orchestrate those workflows, and access your workflows only through a Temporal client.
+[This blog post](https://www.dbos.dev/blog/durable-execution-coding-comparison) makes the comparison in more detail.
+
+**When to use DBOS:** You need to add durable workflows to your applications with minimal rearchitecting, or you are using Postgres.
+
+**When to use Temporal:** You don't want to add Postgres to your stack, or you need a language DBOS doesn't support yet.
+
+</details>
+
+<details><summary><strong>DBOS vs. Airflow</strong></summary>
+
+####
+
+DBOS and Airflow both provide workflow abstractions.
+Airflow is targeted at data science use cases, providing many out-of-the-box connectors but requiring workflows be written as explicit DAGs and externally orchestrating them from an Airflow cluster.
+Airflow is designed for batch operations and does not provide good performance for streaming or real-time use cases.
+DBOS is general-purpose, but is often used for data pipelines, allowing developers to write workflows as code and requiring no infrastructure except Postgres.
+
+**When to use DBOS:** You need the flexibility of writing workflows as code, or you need higher performance than Airflow is capable of (particularly for streaming or real-time use cases).
+
+**When to use Airflow:** You need Airflow's ecosystem of connectors.
+
+</details>
+
+<details><summary><strong>DBOS vs. Celery/BullMQ</strong></summary>
+
+####
+
+DBOS provides a similar queue abstraction to dedicated queueing systems like Celery or BullMQ: you can declare queues, submit tasks to them, and control their flow with concurrency limits, rate limits, timeouts, prioritization, etc.
+However, DBOS queues are **durable and Postgres-backed** and integrate with durable workflows.
+For example, in DBOS you can write a durable workflow that enqueues a thousand tasks and waits for their results.
+DBOS checkpoints the workflow and each of its tasks in Postgres, guaranteeing that even if failures or interruptions occur, the tasks will complete and the workflow will collect their results.
+By contrast, Celery/BullMQ are Redis-backed and don't provide workflows, so they provide fewer guarantees but better performance.
+
+**When to use DBOS:** You need the reliability of enqueueing tasks from durable workflows.
+
+**When to use Celery/BullMQ**: You don't need durability, or you need very high throughput beyond what your Postgres server can support.
+</details>
+
+## Community
+
+If you want to ask questions or hang out with the community, join us on [Discord](https://discord.gg/fMwQjeW5zg)!
+If you see a bug or have a feature request, don't hesitate to open an issue here on GitHub.
+If you're interested in contributing, check out our [contributions guide](./CONTRIBUTING.md).

{dbos-0.27.0a11.dist-info → dbos-0.28.0a4.dist-info}/RECORD

@@ -1,19 +1,19 @@
-dbos-0.27.0a11.dist-info/METADATA,sha256=yw_xz14PUHXYfgd-u1bEU0qU0jmm7nmxV2m5yrCGMZo,5554
-dbos-0.27.0a11.dist-info/WHEEL,sha256=tSfRZzRHthuv7vxpI4aehrdN9scLjk-dCJkPLzkHxGg,90
-dbos-0.27.0a11.dist-info/entry_points.txt,sha256=_QOQ3tVfEjtjBlr1jS4sHqHya9lI2aIEIWkz8dqYp14,58
-dbos-0.27.0a11.dist-info/licenses/LICENSE,sha256=VGZit_a5-kdw9WT6fY5jxAWVwGQzgLFyPWrcVVUhVNU,1067
+dbos-0.28.0a4.dist-info/METADATA,sha256=KyMx9FTut8a9dhtuvbD5FingAQayckrfPUj4wjrGCZQ,13268
+dbos-0.28.0a4.dist-info/WHEEL,sha256=tSfRZzRHthuv7vxpI4aehrdN9scLjk-dCJkPLzkHxGg,90
+dbos-0.28.0a4.dist-info/entry_points.txt,sha256=_QOQ3tVfEjtjBlr1jS4sHqHya9lI2aIEIWkz8dqYp14,58
+dbos-0.28.0a4.dist-info/licenses/LICENSE,sha256=VGZit_a5-kdw9WT6fY5jxAWVwGQzgLFyPWrcVVUhVNU,1067
 dbos/__init__.py,sha256=-FdBlOlr-f2tY__C23J4v22MoCAXqcDN_-zXsJXdoZ0,1005
 dbos/__main__.py,sha256=G7Exn-MhGrVJVDbgNlpzhfh8WMX_72t3_oJaFT9Lmt8,653
 dbos/_admin_server.py,sha256=NG0JWQQer9kEslPNAA0dBv-O262sjarz7ZSlv8yird0,9053
 dbos/_app_db.py,sha256=3j8_5-MlSDY0otLRszFE-GfenU6JC20fcfSL-drSNYk,11800
 dbos/_classproperty.py,sha256=f0X-_BySzn3yFDRKB2JpCbLYQ9tLwt1XftfshvY7CBs,626
-dbos/_client.py,sha256=Id-jzAUH6JMN-9WmAGyo0vm-nc0URjNIVwA2iKnCN5Q,13418
+dbos/_client.py,sha256=Cn-feSnOcuDNnBfP0UBvb3xUWSmaLuoSc8CKQAoDwP8,13931
 dbos/_conductor/conductor.py,sha256=HYzVL29IMMrs2Mnms_7cHJynCnmmEN5SDQOMjzn3UoU,16840
 dbos/_conductor/protocol.py,sha256=zEKIuOQdIaSduNqfZKpo8PSD9_1oNpKIPnBNCu3RUyE,6681
-dbos/_context.py,sha256=5aJHOjh6-2Zc7Fwzw924Vg0utLEkaR-oBMRdz3cE95k,23680
-dbos/_core.py,sha256=7zhdO-VfZe84wgOzBVsliqO-BI20OzcLTFqvrGyxttw,48425
+dbos/_context.py,sha256=fX_lWKx2_bHNTigVkuDtjDfX7BIeCsdDAQ1u47A2_Fo,24590
+dbos/_core.py,sha256=1hDRqEmm77GUJVY1xCEzYsUP_HzLGtflI_v3TCxkQuI,48569
 dbos/_croniter.py,sha256=XHAyUyibs_59sJQfSNWkP7rqQY6_XrlfuuCxk4jYqek,47559
-dbos/_dbos.py,sha256=ENDQ6Xi4MoKrjXoCRlk1B64yZP7D-MyDUjUlOTRsw9I,48314
+dbos/_dbos.py,sha256=f0SnnWL-koLgohj8IaV6l5-tKDtnKpJgAYyel-SwYaE,48346
 dbos/_dbos_config.py,sha256=L0Z0OOB5FoPM9g-joZqXGeJnlxWQsEUtgPtgtg9Uf48,21732
 dbos/_debug.py,sha256=MNlQVZ6TscGCRQeEEL0VE8Uignvr6dPeDDDefS3xgIE,1823
 dbos/_docker_pg_helper.py,sha256=NmcgqmR5rQA_4igfeqh8ugNT2z3YmoOvuep_MEtxTiY,5854
@@ -31,6 +31,7 @@ dbos/_migrations/versions/27ac6900c6ad_add_queue_dedup.py,sha256=56w1v6TdofW3V18
 dbos/_migrations/versions/50f3227f0b4b_fix_job_queue.py,sha256=ZBYrtTdxy64HxIAlOes89fVIk2P1gNaJack7wuC_epg,873
 dbos/_migrations/versions/5c361fc04708_added_system_tables.py,sha256=Xr9hBDJjkAtymlauOmAy00yUHj0VVUaEz7kNwEM9IwE,6403
 dbos/_migrations/versions/83f3732ae8e7_workflow_timeout.py,sha256=Q_R35pb8AfVI3sg5mzKwyoPfYB88Ychcc8gwxpM9R7A,1035
+dbos/_migrations/versions/933e86bdac6a_add_queue_priority.py,sha256=yZX2kGF33skpXIBdMXtDNx-Nl_orFatKeHB8c-3K8-c,773
 dbos/_migrations/versions/a3b18ad34abe_added_triggers.py,sha256=Rv0ZsZYZ_WdgGEULYsPfnp4YzaO5L198gDTgYY39AVA,2022
 dbos/_migrations/versions/d76646551a6b_job_queue_limiter.py,sha256=8PyFi8rd6CN-mUro43wGhsg5wcQWKZPRHD6jw8R5pVc,986
 dbos/_migrations/versions/d76646551a6c_workflow_queue.py,sha256=G942nophZ2uC2vc4hGBC02Ptng1715roTjY3xiyzZU4,729
@@ -45,9 +46,9 @@ dbos/_roles.py,sha256=iOsgmIAf1XVzxs3gYWdGRe1B880YfOw5fpU7Jwx8_A8,2271
 dbos/_scheduler.py,sha256=SR1oRZRcVzYsj-JauV2LA8JtwTkt8mru7qf6H1AzQ1U,2027
 dbos/_schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dbos/_schemas/application_database.py,sha256=SypAS9l9EsaBHFn9FR8jmnqt01M74d9AF1AMa4m2hhI,1040
-dbos/_schemas/system_database.py,sha256=wLqrhApNqrwZC1SdUxi_ca0y_66WzKaaBOxvND4_bdg,5738
+dbos/_schemas/system_database.py,sha256=VVjMUfxPwFMdZPBazNkO00ufG6SgL9OCybLcwC9CiVk,5883
 dbos/_serialization.py,sha256=bWuwhXSQcGmiazvhJHA5gwhrRWxtmFmcCFQSDJnqqkU,3666
-dbos/_sys_db.py,sha256=caIbhOwAnfugGzhnJ5rOG2V_bXphD9tJ4Un37gnG47A,82281
+dbos/_sys_db.py,sha256=r9a3RA9hUogRJ9v3gNol_CjTFKjRhIO9aFaXXLc7G_Y,82820
 dbos/_templates/dbos-db-starter/README.md,sha256=GhxhBj42wjTt1fWEtwNriHbJuKb66Vzu89G4pxNHw2g,930
 dbos/_templates/dbos-db-starter/__package/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dbos/_templates/dbos-db-starter/__package/main.py,sha256=nJMN3ZD2lmwg4Dcgmiwqc-tQGuCJuJal2Xl85iA277U,2453
@@ -59,12 +60,12 @@ dbos/_templates/dbos-db-starter/migrations/script.py.mako,sha256=MEqL-2qATlST9TA
 dbos/_templates/dbos-db-starter/migrations/versions/2024_07_31_180642_init.py,sha256=MpS7LGaJS0CpvsjhfDkp9EJqvMvVCjRPfUp4c0aE2ys,941
 dbos/_templates/dbos-db-starter/start_postgres_docker.py,sha256=lQVLlYO5YkhGPEgPqwGc7Y8uDKse9HsWv5fynJEFJHM,1681
 dbos/_tracer.py,sha256=yN6GRDKu_1p-EqtQLNarMocPfga2ZuqpzStzzSPYhzo,2732
-dbos/_utils.py,sha256=nFRUHzVjXG5AusF85AlYHikj63Tzi-kQm992ihsrAxA,201
+dbos/_utils.py,sha256=pu8qvhZ__44LRCxO4xSb6OuyTuIV4DP-yWT22p2IuVM,477
 dbos/_workflow_commands.py,sha256=7_f8-w0MbS1gqC5v68EwzbUtomVM0lLebozpHxXmRYg,3982
 dbos/cli/_github_init.py,sha256=Y_bDF9gfO2jB1id4FV5h1oIxEJRWyqVjhb7bNEa5nQ0,3224
 dbos/cli/_template_init.py,sha256=-WW3kbq0W_Tq4WbMqb1UGJG3xvJb3woEY5VspG95Srk,2857
-dbos/cli/cli.py,sha256=a3rUrHog5-e22KjjUPOuTjH20PmUgSP0amRpMd6LVJE,18882
+dbos/cli/cli.py,sha256=gXKELYAK9_CTejQ-WbNEIqnEYByJndXHDYSX4naFg8g,19106
 dbos/dbos-config.schema.json,sha256=8KcwJb_sQc4-6tQG2TLmjE_nratfrQa0qVLl9XPsvWE,6367
 dbos/py.typed,sha256=QfzXT1Ktfk3Rj84akygc7_42z0lRpCq0Ilh8OXI6Zas,44
 version/__init__.py,sha256=L4sNxecRuqdtSFdpUGX3TtBi9KL3k7YsZVIvv-fv9-A,1678
-dbos-0.27.0a11.dist-info/RECORD,,
+dbos-0.28.0a4.dist-info/RECORD,,

dbos-0.27.0a11.dist-info/METADATA

@@ -1,145 +0,0 @@
-Metadata-Version: 2.1
-Name: dbos
-Version: 0.27.0a11
-Summary: Ultra-lightweight durable execution in Python
-Author-Email: "DBOS, Inc." <contact@dbos.dev>
-License: MIT
-Requires-Python: >=3.9
-Requires-Dist: pyyaml>=6.0.2
-Requires-Dist: jsonschema>=4.23.0
-Requires-Dist: alembic>=1.13.3
-Requires-Dist: typing-extensions>=4.12.2; python_version < "3.10"
-Requires-Dist: typer>=0.12.5
-Requires-Dist: jsonpickle>=3.3.0
-Requires-Dist: opentelemetry-api>=1.27.0
-Requires-Dist: opentelemetry-sdk>=1.27.0
-Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
-Requires-Dist: python-dateutil>=2.9.0.post0
-Requires-Dist: fastapi[standard]>=0.115.2
-Requires-Dist: tomlkit>=0.13.2
-Requires-Dist: psycopg[binary]>=3.1
-Requires-Dist: docker>=7.1.0
-Requires-Dist: cryptography>=43.0.3
-Requires-Dist: rich>=13.9.4
-Requires-Dist: pyjwt>=2.10.1
-Requires-Dist: websockets>=15.0
-Requires-Dist: pyright>=1.1.398
-Description-Content-Type: text/markdown
-
-
-<div align="center">
-
-# DBOS Transact: A Lightweight Durable Execution Library Built on Postgres
-
-#### [Documentation](https://docs.dbos.dev/) &nbsp;&nbsp;•&nbsp;&nbsp;  [Examples](https://docs.dbos.dev/examples) &nbsp;&nbsp;•&nbsp;&nbsp; [Github](https://github.com/dbos-inc) &nbsp;&nbsp;•&nbsp;&nbsp; [Discord](https://discord.com/invite/jsmC6pXGgX)
-</div>
-
----
-
-DBOS Transact is a Python library for **ultra-lightweight durable execution**.
-For example:
-
-```python
-@DBOS.step()
-def step_one():
-    ...
-
-@DBOS.step()
-def step_two():
-    ...
-
-@DBOS.workflow()
-def workflow()
-    step_one()
-    step_two()
-```
-
-Durable execution means your program is **resilient to any failure**.
-If it is ever interrupted or crashes, all your workflows will automatically resume from the last completed step.
-Durable execution helps solve many common problems:
-
-- Orchestrating long-running or business-critical workflows so they seamlessly recover from any failure.
-- Running reliable background jobs with no timeouts.
-- Processing incoming events (e.g. from Kafka) exactly once.
-- Running a fault-tolerant distributed task queue.
-- Running a reliable cron scheduler.
-- Operating an AI agent, or anything that connects to an unreliable or non-deterministic API.
-
-What’s unique about DBOS's implementation of durable execution is that it’s implemented in a **lightweight library** that’s **totally backed by Postgres**.
-To use DBOS, just `pip install` it and annotate your program with DBOS decorators.
-Under the hood, those decorators store your program's execution state (which workflows are currently executing and which steps they've completed) in a Postgres database.
-If your program crashes or is interrupted, they automatically recover its workflows from their stored state.
-So all you need to use DBOS is Postgres&mdash;there are no other dependencies you have to manage, no separate workflow server.
-
-One big advantage of this approach is that you can add DBOS to **any** Python application&mdash;**it’s just a library**.
-You can use DBOS to add reliable background jobs or cron scheduling or queues to your app with no external dependencies except Postgres.
-
-## Getting Started
-
-Install and configure with:
-
-```shell
-python3 -m venv dbos-example/.venv
-cd dbos-example
-source .venv/bin/activate
-pip install dbos
-dbos init --config
-```
-
-Then, try it out with this simple program:
-
-```python
-from fastapi import FastAPI
-from dbos import DBOS
-
-app = FastAPI()
-DBOS(fastapi=app)
-
-@DBOS.step()
-def step_one():
-    print("Step one completed!")
-
-@DBOS.step()
-def step_two():
-    print("Step two completed!")
-
-@DBOS.workflow()
-def dbos_workflow():
-    step_one()
-    for _ in range(5):
-        print("Press Control + C twice to stop the app...")
-        DBOS.sleep(1)
-    step_two()
-
-@app.get("/")
-def fastapi_endpoint():
-    dbos_workflow()
-```
-
-Save the program into `main.py` and start it with `fastapi run`.
-Visit `localhost:8000` in your browser to start the workflow.
-When prompted, press `Control + C` (You may need to press `Control + C` twice quickly, or press `Control + \`, if `Control + C` is not effective in your environment) to force quit your application.
-It should crash midway through the workflow, having completed step one but not step two.
-Then, restart your app with `fastapi run`.
-It should resume the workflow from where it left off, completing step two without re-executing step one.
-
-To learn how to build more complex workflows, see the [programming guide](https://docs.dbos.dev/python/programming-guide) or [examples](https://docs.dbos.dev/examples).
-
-## Documentation
-
-[https://docs.dbos.dev](https://docs.dbos.dev)
-
-## Examples
-
-
-- [**AI-Powered Slackbot**](https://docs.dbos.dev/python/examples/rag-slackbot) &mdash; A Slackbot that answers questions about previous Slack conversations, using DBOS to durably orchestrate its RAG pipeline.
-- [**Widget Store**](https://docs.dbos.dev/python/examples/widget-store) &mdash; An online storefront that uses DBOS durable workflows to be resilient to any failure.
-- [**Scheduled Reminders**](https://docs.dbos.dev/python/examples/scheduled-reminders) &mdash; In just three lines of code, schedule an email to send days, weeks, or months in the future.
-
-More examples [here](https://docs.dbos.dev/examples)!
-
-## Community
-
-If you're interested in building with us, please star our repository and join our community on [Discord](https://discord.gg/fMwQjeW5zg)!
-If you see a bug or have a feature request, don't hesitate to open an issue here on GitHub.
-If you're interested in contributing, check out our [contributions guide](./CONTRIBUTING.md).