dbos 0.5.0a12__tar.gz → 0.6.0__tar.gz

{dbos-0.5.0a12 → dbos-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dbos
-Version: 0.5.0a12
+Version: 0.6.0
 Summary: Ultra-lightweight durable execution in Python
 Author-Email: "DBOS, Inc." <contact@dbos.dev>
 License: MIT
@@ -21,20 +21,17 @@ Requires-Dist: psutil>=6.0.0
 Requires-Dist: tomlkit>=0.13.2
 Description-Content-Type: text/markdown
 
-## 🚀 DBOS Transact - Ultra-Lightweight Durable Execution in Python 🚀
 
----
+<div align="center">
 
-📚 **Documentation**: Under Construction 🚧
+# DBOS Transact: Ultra-Lightweight Durable Execution
 
-💬 **Join the Discussion**: [Discord Community](https://discord.gg/fMwQjeW5zg)
+#### [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 Python is under construction! 🚧🚧🚧 Check back regularly for updates, release coming in mid-September!**
-
-DBOS Transact is a **Python library** providing ultra-lightweight durable execution.
+DBOS Transact is a Python library providing **ultra-lightweight durable execution**.
 For example:
 
 ```python
@@ -69,14 +66,14 @@ Some more cool features include:
 
 ## Getting Started
 
-To try out the latest pre-release version, install and configure with:
+Install and configure with:
 
 ```shell
-pip install --pre dbos
+pip install dbos
 dbos init --config
 ```
 
-Try it out with this simple program (requires Postgres):
+Then, try it out with this simple program (requires Postgres):
 
 ```python
 from fastapi import FastAPI
@@ -106,22 +103,27 @@ def endpoint():
     workflow()
 ```
 
-Save the program into `main.py`, tell it your local Postgres password via `export PGPASSWORD=<your password>` and start it with `fastapi run`.
-Visit `localhost:8000` in your browser (or curl it) to start the workflow.
+Save the program into `main.py`, edit `dbos-config.yaml` to configure your Postgres connection settings, and start it with `fastapi run`.
+Visit `localhost:8000` in your browser to start the workflow.
 When prompted, press `Control + \` 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 examples, see our programming guide (coming soon).
+To learn how to build more complex workflows, see our [programming guide](https://docs.dbos.dev/python/programming-guide) or [examples](https://docs.dbos.dev/examples).
 
 ## Documentation
 
-Coming soon! 🚧
+[https://docs.dbos.dev](https://docs.dbos.dev)
 
 ## Examples
 
-Check out some cool demo apps here: [https://github.com/dbos-inc/dbos-demo-apps/tree/main/python](https://github.com/dbos-inc/dbos-demo-apps/tree/main/python)
+
+- [**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.
+- [**Earthquake Tracker**](https://docs.dbos.dev/python/examples/earthquake-tracker) &mdash; A real-time earthquake dashboard that uses DBOS to stream data from the USGS into Postgres, then visualizes it with Streamlit.
+
+More examples [here](https://docs.dbos.dev/examples)!
 
 ## Community
 

{dbos-0.5.0a12 → dbos-0.6.0}/README.md

@@ -1,17 +1,14 @@
-## 🚀 DBOS Transact - Ultra-Lightweight Durable Execution in Python 🚀
 
----
+<div align="center">
 
-📚 **Documentation**: Under Construction 🚧
+# DBOS Transact: Ultra-Lightweight Durable Execution
 
-💬 **Join the Discussion**: [Discord Community](https://discord.gg/fMwQjeW5zg)
+#### [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 Python is under construction! 🚧🚧🚧 Check back regularly for updates, release coming in mid-September!**
-
-DBOS Transact is a **Python library** providing ultra-lightweight durable execution.
+DBOS Transact is a Python library providing **ultra-lightweight durable execution**.
 For example:
 
 ```python
@@ -46,14 +43,14 @@ Some more cool features include:
 
 ## Getting Started
 
-To try out the latest pre-release version, install and configure with:
+Install and configure with:
 
 ```shell
-pip install --pre dbos
+pip install dbos
 dbos init --config
 ```
 
-Try it out with this simple program (requires Postgres):
+Then, try it out with this simple program (requires Postgres):
 
 ```python
 from fastapi import FastAPI
@@ -83,22 +80,27 @@ def endpoint():
     workflow()
 ```
 
-Save the program into `main.py`, tell it your local Postgres password via `export PGPASSWORD=<your password>` and start it with `fastapi run`.
-Visit `localhost:8000` in your browser (or curl it) to start the workflow.
+Save the program into `main.py`, edit `dbos-config.yaml` to configure your Postgres connection settings, and start it with `fastapi run`.
+Visit `localhost:8000` in your browser to start the workflow.
 When prompted, press `Control + \` 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 examples, see our programming guide (coming soon).
+To learn how to build more complex workflows, see our [programming guide](https://docs.dbos.dev/python/programming-guide) or [examples](https://docs.dbos.dev/examples).
 
 ## Documentation
 
-Coming soon! 🚧
+[https://docs.dbos.dev](https://docs.dbos.dev)
 
 ## Examples
 
-Check out some cool demo apps here: [https://github.com/dbos-inc/dbos-demo-apps/tree/main/python](https://github.com/dbos-inc/dbos-demo-apps/tree/main/python)
+
+- [**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.
+- [**Earthquake Tracker**](https://docs.dbos.dev/python/examples/earthquake-tracker) &mdash; A real-time earthquake dashboard that uses DBOS to stream data from the USGS into Postgres, then visualizes it with Streamlit.
+
+More examples [here](https://docs.dbos.dev/examples)!
 
 ## Community
 

dbos-0.6.0/dbos/__init__.py

@@ -0,0 +1,22 @@
+from . import error as error
+from .context import DBOSContextEnsure, SetWorkflowID
+from .dbos import DBOS, DBOSConfiguredInstance, WorkflowHandle, WorkflowStatus
+from .dbos_config import ConfigFile, get_dbos_database_url, load_config
+from .kafka_message import KafkaMessage
+from .system_database import GetWorkflowsInput, WorkflowStatusString
+
+__all__ = [
+    "ConfigFile",
+    "DBOS",
+    "DBOSConfiguredInstance",
+    "DBOSContextEnsure",
+    "GetWorkflowsInput",
+    "KafkaMessage",
+    "SetWorkflowID",
+    "WorkflowHandle",
+    "WorkflowStatus",
+    "WorkflowStatusString",
+    "load_config",
+    "get_dbos_database_url",
+    "error",
+]

{dbos-0.5.0a12 → dbos-0.6.0}/dbos/context.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import os
 import uuid
 from contextvars import ContextVar
@@ -39,6 +40,9 @@ class TracedAttributes(TypedDict, total=False):
     applicationID: Optional[str]
     applicationVersion: Optional[str]
     executorID: Optional[str]
+    authenticatedUser: Optional[str]
+    authenticatedUserRoles: Optional[str]
+    authenticatedUserAssumedRole: Optional[str]
 
 
 class DBOSContext:
@@ -159,6 +163,13 @@ class DBOSContext:
         attributes["operationUUID"] = (
             self.workflow_id if len(self.workflow_id) > 0 else None
         )
+        attributes["authenticatedUser"] = self.authenticated_user
+        attributes["authenticatedUserRoles"] = (
+            json.dumps(self.authenticated_roles)
+            if self.authenticated_roles is not None
+            else ""
+        )
+        attributes["authenticatedUserAssumedRole"] = self.assumed_role
         span = dbos_tracer.start_span(
             attributes, parent=self.spans[-1] if len(self.spans) > 0 else None
         )
@@ -178,6 +189,11 @@ class DBOSContext:
     ) -> None:
         self.authenticated_user = user
         self.authenticated_roles = roles
+        if user is not None and len(self.spans) > 0:
+            self.spans[-1].set_attribute("authenticatedUser", user)
+            self.spans[-1].set_attribute(
+                "authenticatedUserRoles", json.dumps(roles) if roles is not None else ""
+            )
 
 
 ##############################################################
@@ -217,13 +233,13 @@ class DBOSContextEnsure:
     def __init__(self) -> None:
         self.created_ctx = False
 
-    def __enter__(self) -> DBOSContextEnsure:
+    def __enter__(self) -> DBOSContext:
         # Code to create a basic context
         ctx = get_local_dbos_context()
         if ctx is None:
             self.created_ctx = True
             set_local_dbos_context(DBOSContext())
-        return self
+        return assert_current_dbos_context()
 
     def __exit__(
         self,

{dbos-0.5.0a12 → dbos-0.6.0}/dbos/core.py

@@ -1,9 +1,20 @@
+import json
 import sys
 import time
 import traceback
 from concurrent.futures import Future
 from functools import wraps
-from typing import TYPE_CHECKING, Any, Callable, Generic, Optional, Tuple, TypeVar, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    List,
+    Optional,
+    Tuple,
+    TypeVar,
+    cast,
+)
 
 from dbos.application_database import ApplicationDatabase, TransactionResultInternal
 
@@ -134,6 +145,11 @@ def _init_workflow(
         "executor_id": ctx.executor_id,
         "request": (utils.serialize(ctx.request) if ctx.request is not None else None),
         "recovery_attempts": None,
+        "authenticated_user": ctx.authenticated_user,
+        "authenticated_roles": (
+            json.dumps(ctx.authenticated_roles) if ctx.authenticated_roles else None
+        ),
+        "assumed_role": ctx.assumed_role,
     }
 
     # If we have a class name, the first arg is the instance and do not serialize

{dbos-0.5.0a12 → dbos-0.6.0}/dbos/dbos.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import atexit
+import json
 import os
 import sys
 import threading
@@ -19,6 +20,7 @@ from typing import (
     Tuple,
     Type,
     TypeVar,
+    cast,
 )
 
 from opentelemetry.trace import Span
@@ -52,10 +54,14 @@ from .tracer import dbos_tracer
 
 if TYPE_CHECKING:
     from fastapi import FastAPI
+    from dbos.kafka import KafkaConsumerWorkflow
     from .request import Request
+    from flask import Flask
 
 from sqlalchemy.orm import Session
 
+from dbos.request import Request
+
 if sys.version_info < (3, 10):
     from typing_extensions import ParamSpec, TypeAlias
 else:
@@ -205,6 +211,7 @@ class DBOS:
         *,
         config: Optional[ConfigFile] = None,
         fastapi: Optional["FastAPI"] = None,
+        flask: Optional["Flask"] = None,
     ) -> DBOS:
         global _dbos_global_instance
         global _dbos_global_registry
@@ -219,7 +226,7 @@ class DBOS:
                     )
                 config = _dbos_global_registry.config
             _dbos_global_instance = super().__new__(cls)
-            _dbos_global_instance.__init__(fastapi=fastapi, config=config)  # type: ignore
+            _dbos_global_instance.__init__(fastapi=fastapi, config=config, flask=flask)  # type: ignore
         else:
             if (config is not None and _dbos_global_instance.config is not config) or (
                 _dbos_global_instance.fastapi is not fastapi
@@ -243,6 +250,7 @@ class DBOS:
         *,
         config: Optional[ConfigFile] = None,
         fastapi: Optional["FastAPI"] = None,
+        flask: Optional["Flask"] = None,
     ) -> None:
         if hasattr(self, "_initialized") and self._initialized:
             return
@@ -264,14 +272,44 @@ class DBOS:
         self._admin_server: Optional[AdminServer] = None
         self.stop_events: List[threading.Event] = []
         self.fastapi: Optional["FastAPI"] = fastapi
+        self.flask: Optional["Flask"] = flask
         self._executor: Optional[ThreadPoolExecutor] = None
+
+        # If using FastAPI, set up middleware and lifecycle events
         if self.fastapi is not None:
+            from fastapi.requests import Request as FARequest
+            from fastapi.responses import JSONResponse
+
+            async def dbos_error_handler(
+                request: FARequest, gexc: Exception
+            ) -> JSONResponse:
+                exc: DBOSException = cast(DBOSException, gexc)
+                status_code = 500
+                if exc.status_code is not None:
+                    status_code = exc.status_code
+                return JSONResponse(
+                    status_code=status_code,
+                    content={
+                        "message": str(exc.message),
+                        "dbos_error_code": str(exc.dbos_error_code),
+                        "dbos_error": str(exc.__class__.__name__),
+                    },
+                )
+
+            self.fastapi.add_exception_handler(DBOSException, dbos_error_handler)
+
             from dbos.fastapi import setup_fastapi_middleware
 
             setup_fastapi_middleware(self.fastapi)
             self.fastapi.on_event("startup")(self._launch)
             self.fastapi.on_event("shutdown")(self._destroy)
 
+        # If using Flask, set up middleware
+        if self.flask is not None:
+            from dbos.flask import setup_flask_middleware
+
+            setup_flask_middleware(self.flask)
+
         # Register send_stub as a workflow
         def send_temp_workflow(
             destination_id: str, message: Any, topic: Optional[str]
@@ -471,6 +509,20 @@ class DBOS:
 
         return scheduled(_get_or_create_dbos_registry(), cron)
 
+    @classmethod
+    def kafka_consumer(
+        cls, config: dict[str, Any], topics: list[str]
+    ) -> Callable[[KafkaConsumerWorkflow], KafkaConsumerWorkflow]:
+        """Decorate a function to be used as a Kafka consumer."""
+        try:
+            from dbos.kafka import kafka_consumer
+
+            return kafka_consumer(_get_or_create_dbos_registry(), config, topics)
+        except ModuleNotFoundError as e:
+            raise DBOSException(
+                f"{e.name} dependency not found. Please install {e.name} via your package manager."
+            ) from e
+
     @classmethod
     def start_workflow(
         cls,
@@ -502,9 +554,13 @@ class DBOS:
             recovery_attempts=stat["recovery_attempts"],
             class_name=stat["class_name"],
             config_name=stat["config_name"],
-            authenticated_user=None,
-            assumed_role=None,
-            authenticatedRoles=None,
+            authenticated_user=stat["authenticated_user"],
+            assumed_role=stat["assumed_role"],
+            authenticated_roles=(
+                json.loads(stat["authenticated_roles"])
+                if stat["authenticated_roles"] is not None
+                else None
+            ),
         )
 
     @classmethod
@@ -663,6 +719,33 @@ class DBOS:
         ctx = assert_current_dbos_context()
         return ctx.request
 
+    @classproperty
+    def authenticated_user(cls) -> Optional[str]:
+        """Return the current authenticated user, if any, associated with the current context."""
+        ctx = assert_current_dbos_context()
+        return ctx.authenticated_user
+
+    @classproperty
+    def authenticated_roles(cls) -> Optional[List[str]]:
+        """Return the roles granted to the current authenticated user, if any, associated with the current context."""
+        ctx = assert_current_dbos_context()
+        return ctx.authenticated_roles
+
+    @classproperty
+    def assumed_role(cls) -> Optional[str]:
+        """Return the role currently assumed by the authenticated user, if any, associated with the current context."""
+        ctx = assert_current_dbos_context()
+        return ctx.assumed_role
+
+    @classmethod
+    def set_authentication(
+        cls, authenticated_user: Optional[str], authenticated_roles: Optional[List[str]]
+    ) -> None:
+        """Set the current authenticated user and granted roles into the current context."""
+        ctx = assert_current_dbos_context()
+        ctx.authenticated_user = authenticated_user
+        ctx.authenticated_roles = authenticated_roles
+
 
 @dataclass
 class WorkflowStatus:
@@ -679,7 +762,7 @@ class WorkflowStatus:
         config_name(str): For instance member functions, the name of the class instance for the execution
         authenticated_user(str): The user who invoked the workflow
         assumed_role(str): The access role used by the user to allow access to the workflow function
-        authenticatedRoles(List[str]): List of all access roles available to the authenticated user
+        authenticated_roles(List[str]): List of all access roles available to the authenticated user
         recovery_attempts(int): Number of times the workflow has been restarted (usually by recovery)
 
     """
@@ -691,7 +774,7 @@ class WorkflowStatus:
     config_name: Optional[str]
     authenticated_user: Optional[str]
     assumed_role: Optional[str]
-    authenticatedRoles: Optional[List[str]]
+    authenticated_roles: Optional[List[str]]
     recovery_attempts: Optional[int]
 
 
@@ -740,13 +823,9 @@ class DBOSConfiguredInstance:
 
     """
 
-    def __init__(self, config_name: str, dbos: Optional[DBOS] = None) -> None:
+    def __init__(self, config_name: str) -> None:
         self.config_name = config_name
-        if dbos is not None:
-            assert isinstance(dbos, DBOS)
-            dbos._registry.register_instance(self)
-        else:
-            DBOS.register_instance(self)
+        DBOS.register_instance(self)
 
 
 # Apps that import DBOS probably don't exit.  If they do, let's see if

{dbos-0.5.0a12 → dbos-0.6.0}/dbos/dbos_config.py

@@ -69,6 +69,7 @@ class ConfigFile(TypedDict, total=False):
     database: DatabaseConfig
     telemetry: Optional[TelemetryConfig]
     env: Dict[str, str]
+    application: Dict[str, Any]
 
 
 def substitute_env_vars(content: str) -> str:

{dbos-0.5.0a12 → dbos-0.6.0}/dbos/error.py

@@ -17,6 +17,7 @@ class DBOSException(Exception):
     def __init__(self, message: str, dbos_error_code: Optional[int] = None):
         self.message = message
         self.dbos_error_code = dbos_error_code
+        self.status_code: Optional[int] = None
         super().__init__(self.message)
 
     def __str__(self) -> str:
@@ -104,6 +105,7 @@ class DBOSNotAuthorizedError(DBOSException):
             msg,
             dbos_error_code=DBOSErrorCode.NotAuthorized.value,
         )
+        self.status_code = 403
 
 
 class DBOSMaxStepRetriesExceeded(DBOSException):

{dbos-0.5.0a12 → dbos-0.6.0}/dbos/fastapi.py

@@ -11,9 +11,7 @@ from .context import (
     TracedAttributes,
     assert_current_dbos_context,
 )
-from .request import Address, Request
-
-request_id_header = "x-request-id"
+from .request import Address, Request, request_id_header
 
 
 def get_or_generate_request_id(request: FastAPIRequest) -> str:

dbos-0.6.0/dbos/flask.py

@@ -0,0 +1,79 @@
+import uuid
+from typing import Any
+from urllib.parse import urlparse
+
+from flask import Flask, request
+from werkzeug.wrappers import Request as WRequest
+
+from dbos.context import (
+    EnterDBOSHandler,
+    OperationType,
+    SetWorkflowID,
+    TracedAttributes,
+    assert_current_dbos_context,
+)
+
+from .request import Address, Request, request_id_header
+
+
+class FlaskMiddleware:
+    def __init__(self, app: Any) -> None:
+        self.app = app
+
+    def __call__(self, environ: Any, start_response: Any) -> Any:
+        request = WRequest(environ)
+        attributes: TracedAttributes = {
+            "name": urlparse(request.url).path,
+            "requestID": get_or_generate_request_id(request),
+            "requestIP": (
+                request.remote_addr if request.remote_addr is not None else None
+            ),
+            "requestURL": request.url,
+            "requestMethod": request.method,
+            "operationType": OperationType.HANDLER.value,
+        }
+        with EnterDBOSHandler(attributes):
+            ctx = assert_current_dbos_context()
+            ctx.request = make_request(request)
+            workflow_id = request.headers.get("dbos-idempotency-key", "")
+            with SetWorkflowID(workflow_id):
+                response = self.app(environ, start_response)
+        return response
+
+
+def get_or_generate_request_id(request: WRequest) -> str:
+    request_id = request.headers.get(request_id_header, None)
+    if request_id is not None:
+        return request_id
+    else:
+        return str(uuid.uuid4())
+
+
+def make_request(request: WRequest) -> Request:
+    parsed_url = urlparse(request.url)
+    base_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
+
+    client = None
+    if request.remote_addr:
+        hostname = request.remote_addr
+        port = request.environ.get("REMOTE_PORT")
+        if port:
+            client = Address(hostname=hostname, port=int(port))
+        else:
+            # If port is not available, use 0 as a placeholder
+            client = Address(hostname=hostname, port=0)
+
+    return Request(
+        headers=dict(request.headers),
+        path_params={},
+        query_params=dict(request.args),
+        url=request.url,
+        base_url=base_url,
+        client=client,
+        cookies=dict(request.cookies),
+        method=request.method,
+    )
+
+
+def setup_flask_middleware(app: Flask) -> None:
+    app.wsgi_app = FlaskMiddleware(app.wsgi_app)  # type: ignore