dbos-python

Files (37)

• AGENTS.md
• CLAUDE.md
• SKILL.md
• _sections.md · references/
• advanced-async.md · references/
• advanced-patching.md · references/
• advanced-serialization.md · references/
• advanced-versioning.md · references/
• client-enqueue.md · references/
• client-setup.md · references/
• comm-events.md · references/
• comm-messages.md · references/
• comm-streaming.md · references/
• lifecycle-config.md · references/
• lifecycle-fastapi.md · references/
• pattern-classes.md · references/
• pattern-debouncing.md · references/
• pattern-idempotency.md · references/
• pattern-scheduled.md · references/
• pattern-sleep.md · references/
• queue-basics.md · references/
• queue-concurrency.md · references/
• queue-deduplication.md · references/
• queue-listening.md · references/
• queue-partitioning.md · references/
• queue-priority.md · references/
• queue-rate-limiting.md · references/
• step-basics.md · references/
• step-retries.md · references/
• step-transactions.md · references/
• test-fixtures.md · references/
• workflow-background.md · references/
• workflow-constraints.md · references/
• workflow-control.md · references/
• workflow-determinism.md · references/
• workflow-introspection.md · references/
• workflow-timeout.md · references/

SKILL.md (first lines)

# DBOS Python Best Practices

Guide for building reliable, fault-tolerant Python applications with DBOS durable workflows.

## When to Apply

Reference these guidelines when:
- Adding DBOS to existing Python code
- Creating workflows and steps
- Using queues for concurrency control
- Implementing workflow communication (events, messages, streams)
- Configuring and launching DBOS applications
- Using DBOSClient from external applications
- Testing DBOS applications

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Lifecycle | CRITICAL | `lifecycle-` |
| 2 | Workflow | CRITICAL | `workflow-` |
| 3 | Step | HIGH | `step-` |
| 4 | Queue | HIGH | `queue-` |
| 5 | Communication | MEDIUM | `comm-` |
| 6 | Pattern | MEDIUM | `pattern-` |
| 7 | Testing | LOW-MEDIUM | `test-` |
| 8 | Client | MEDIUM | `client-` |
| 9 | Advanced | LOW | `advanced-` |

## Critical Rules

### DBOS Configuration and Launch

A DBOS application MUST configure and launch DBOS inside its main function:

```python
import os
from dbos import DBOS, DBOSConfig

@DBOS.workflow()
def my_workflow():
    pass

if __name__ == "__main__":
    config: DBOSConfig = {
        "name": "my-app",
        "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
    }
    DBOS(config=config)
    DBOS.launch()
```

### Workflow and Step Structure

Workflows are comprised of steps. Any function performing complex operations or accessing external services must be a step:

```python
@DBOS.step()
def call_external_api():
    return requests.get("https://api.example.com").json()

@DBOS.workflow()
def my_workflow():
    result = call_external_api()
    return result
```

### Key Constraints

- Do NOT call `DBOS.start_workflow` or `DBOS.recv` from a step
- Do NOT use threads to start workflows - use `DBOS.start_workflow` or queues
- Workflows MUST be deterministic - non-deterministic operations go in steps
- Do NOT create/update global variables from workflows or steps

## How to Use

Read individual rule files for detailed explanations and examples:

```
references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md
```

## References

- https://docs.dbos.dev/
- https://github.com/dbos-inc/dbos-transact-py

From datasciencemonkey/maestro-decisioning-demo, MIT.

More from datasciencemonkey/maestro-decisioning-demo