openbox-temporal-sdk-python 1.0.1__tar.gz → 1.0.2__tar.gz

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/.github/workflows/publish.yml

@@ -1,9 +1,8 @@
 name: Publish to PyPI
 
 on:
-  push:
-    tags:
-      - "v*"
+  release:
+    types: [created]
 
 jobs:
   publish:

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/.github/workflows/sonarqube.yaml

@@ -117,7 +117,7 @@ jobs:
           cat qg.md >> "$GITHUB_STEP_SUMMARY"
           echo "STATUS=${STATUS}"   >> "$GITHUB_ENV"
           echo "QG_NAME=${QG_NAME}" >> "$GITHUB_ENV"
-          echo "PNAME=${PNAME}"     >> "$GITHUB_ENV"   # truyền sang bước sau
+          echo "PNAME=${PNAME}"     >> "$GITHUB_ENV"
         
       # (2) Upsert Issue cho
       - name: Comment (or create) Issue with QG report

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbox-temporal-sdk-python
-Version: 1.0.1
+Version: 1.0.2
 Summary: OpenBox SDK - Governance and observability for Temporal workflows
 Project-URL: Homepage, https://github.com/OpenBox-AI/temporal-sdk-python
 Project-URL: Documentation, https://github.com/OpenBox-AI/temporal-sdk-python#readme
@@ -140,7 +140,8 @@ worker = create_openbox_worker(
 
     # Database instrumentation
     instrument_databases=True,
-    db_libraries={"psycopg2", "redis"},  # None = all available
+    db_libraries={"psycopg2", "sqlalchemy"},  # None = all available
+    sqlalchemy_engine=engine,  # pass pre-existing engine for query capture
 
     # File I/O instrumentation
     instrument_file_io=False,  # disabled by default
@@ -238,6 +239,18 @@ Configure error policy via `on_api_error`:
 - Redis: `redis`
 - ORM: `sqlalchemy`
 
+**SQLAlchemy Note:** If your SQLAlchemy engine is created before `create_openbox_worker()` runs (e.g., at module import time), you must pass it via the `sqlalchemy_engine` parameter. Without this, `SQLAlchemyInstrumentor` only patches future `create_engine()` calls and won't capture queries on pre-existing engines.
+
+```python
+from db.engine import engine
+
+worker = create_openbox_worker(
+    ...,
+    db_libraries={"psycopg2", "sqlalchemy"},
+    sqlalchemy_engine=engine,
+)
+```
+
 ### File I/O
 - `open()`, `read()`, `write()`, `readline()`, `readlines()`
 - Skips system paths (`/dev/`, `/proc/`, `/sys/`, `__pycache__`)
@@ -284,7 +297,10 @@ span_processor = WorkflowSpanProcessor(
 )
 
 # 3. Setup OTel instrumentation
-setup_opentelemetry_for_governance(span_processor)
+setup_opentelemetry_for_governance(
+    span_processor,
+    sqlalchemy_engine=engine,  # optional: instrument pre-existing engine
+)
 
 # 4. Create governance config
 config = GovernanceConfig(
@@ -355,4 +371,4 @@ MIT License - See LICENSE file for details
 
 ---
 
-**Version:** 1.0.0 | **Last Updated:** 2026-02-04
+**Version:** 1.0.2 | **Last Updated:** 2026-02-12

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/README.md

@@ -91,7 +91,8 @@ worker = create_openbox_worker(
 
     # Database instrumentation
     instrument_databases=True,
-    db_libraries={"psycopg2", "redis"},  # None = all available
+    db_libraries={"psycopg2", "sqlalchemy"},  # None = all available
+    sqlalchemy_engine=engine,  # pass pre-existing engine for query capture
 
     # File I/O instrumentation
     instrument_file_io=False,  # disabled by default
@@ -189,6 +190,18 @@ Configure error policy via `on_api_error`:
 - Redis: `redis`
 - ORM: `sqlalchemy`
 
+**SQLAlchemy Note:** If your SQLAlchemy engine is created before `create_openbox_worker()` runs (e.g., at module import time), you must pass it via the `sqlalchemy_engine` parameter. Without this, `SQLAlchemyInstrumentor` only patches future `create_engine()` calls and won't capture queries on pre-existing engines.
+
+```python
+from db.engine import engine
+
+worker = create_openbox_worker(
+    ...,
+    db_libraries={"psycopg2", "sqlalchemy"},
+    sqlalchemy_engine=engine,
+)
+```
+
 ### File I/O
 - `open()`, `read()`, `write()`, `readline()`, `readlines()`
 - Skips system paths (`/dev/`, `/proc/`, `/sys/`, `__pycache__`)
@@ -235,7 +248,10 @@ span_processor = WorkflowSpanProcessor(
 )
 
 # 3. Setup OTel instrumentation
-setup_opentelemetry_for_governance(span_processor)
+setup_opentelemetry_for_governance(
+    span_processor,
+    sqlalchemy_engine=engine,  # optional: instrument pre-existing engine
+)
 
 # 4. Create governance config
 config = GovernanceConfig(
@@ -306,4 +322,4 @@ MIT License - See LICENSE file for details
 
 ---
 
-**Version:** 1.0.0 | **Last Updated:** 2026-02-04
+**Version:** 1.0.2 | **Last Updated:** 2026-02-12

openbox_temporal_sdk_python-1.0.2/docs/configuration.md

@@ -0,0 +1,63 @@
+# OpenBox SDK Configuration
+
+## Required
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `openbox_url` | `str` | OpenBox Core API URL (HTTPS required for non-localhost) |
+| `openbox_api_key` | `str` | API key (`obx_live_*` or `obx_test_*`) |
+
+## Governance
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `governance_timeout` | `float` | `30.0` | API timeout in seconds |
+| `governance_policy` | `str` | `"fail_open"` | `"fail_open"` or `"fail_closed"` |
+
+## Event Filtering
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `send_start_event` | `bool` | `True` | Send WorkflowStarted events |
+| `send_activity_start_event` | `bool` | `True` | Send ActivityStarted events |
+| `skip_workflow_types` | `set` | `None` | Workflow types to skip |
+| `skip_activity_types` | `set` | `None` | Activity types to skip |
+| `skip_signals` | `set` | `None` | Signal names to skip |
+
+## Human-in-the-Loop
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `hitl_enabled` | `bool` | `True` | Enable approval polling for `REQUIRE_APPROVAL` |
+
+## Instrumentation
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `instrument_databases` | `bool` | `True` | Capture database queries |
+| `db_libraries` | `set` | `None` | `"psycopg2"`, `"asyncpg"`, `"mysql"`, `"pymysql"`, `"pymongo"`, `"redis"`, `"sqlalchemy"` |
+| `instrument_file_io` | `bool` | `False` | Capture file operations |
+
+## Example
+
+```python
+worker = create_openbox_worker(
+    client=client,
+    task_queue="my-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+
+    # Required
+    openbox_url=os.getenv("OPENBOX_URL"),
+    openbox_api_key=os.getenv("OPENBOX_API_KEY"),
+
+    # Optional
+    governance_policy="fail_closed",
+    governance_timeout=15.0,
+    hitl_enabled=True,
+    skip_workflow_types={"InternalWorkflow"},
+    instrument_databases=True,
+    db_libraries={"psycopg2", "redis"},
+    instrument_file_io=False,
+)
+```

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/openbox/otel_setup.py

@@ -22,7 +22,7 @@ Supported database libraries:
 - sqlalchemy (ORM)
 """
 
-from typing import TYPE_CHECKING, Optional, Set, List
+from typing import TYPE_CHECKING, Any, Optional, Set, List
 import logging
 
 if TYPE_CHECKING:
@@ -70,6 +70,7 @@ def setup_opentelemetry_for_governance(
     instrument_databases: bool = True,
     db_libraries: Optional[Set[str]] = None,
     instrument_file_io: bool = False,
+    sqlalchemy_engine: Optional[Any] = None,
 ) -> None:
     """
     Setup OpenTelemetry instrumentors with body capture hooks.
@@ -87,6 +88,10 @@ def setup_opentelemetry_for_governance(
                       Valid values: "psycopg2", "asyncpg", "mysql", "pymysql",
                       "pymongo", "redis", "sqlalchemy"
         instrument_file_io: Whether to instrument file I/O operations (default: False)
+        sqlalchemy_engine: Optional SQLAlchemy Engine instance to instrument. Required
+                          when the engine is created before instrumentation runs (e.g.,
+                          at module import time). If not provided, only future engines
+                          created via create_engine() will be instrumented.
     """
     global _span_processor, _ignored_url_prefixes
     _span_processor = span_processor
@@ -172,8 +177,13 @@ def setup_opentelemetry_for_governance(
     logger.info(f"OpenTelemetry HTTP instrumentation complete. Instrumented: {instrumented}")
 
     # 6. Database instrumentation (optional)
+    if sqlalchemy_engine is not None and not instrument_databases:
+        logger.warning(
+            "sqlalchemy_engine was provided but instrument_databases=False; "
+            "engine will not be instrumented"
+        )
     if instrument_databases:
-        db_instrumented = setup_database_instrumentation(db_libraries)
+        db_instrumented = setup_database_instrumentation(db_libraries, sqlalchemy_engine)
         if db_instrumented:
             instrumented.extend(db_instrumented)
 
@@ -334,6 +344,7 @@ def uninstrument_file_io() -> None:
 
 def setup_database_instrumentation(
     db_libraries: Optional[Set[str]] = None,
+    sqlalchemy_engine: Optional[Any] = None,
 ) -> List[str]:
     """
     Setup OpenTelemetry database instrumentors.
@@ -351,6 +362,10 @@ def setup_database_instrumentation(
                       - "pymongo" (MongoDB)
                       - "redis"
                       - "sqlalchemy" (ORM)
+        sqlalchemy_engine: Optional SQLAlchemy Engine instance to instrument. When
+                          provided, registers event listeners on this engine to capture
+                          queries. Without this, only engines created after this call
+                          (via patched create_engine) will be instrumented.
 
     Returns:
         List of successfully instrumented library names
@@ -424,13 +439,36 @@ def setup_database_instrumentation(
             logger.debug("redis instrumentation not available")
 
     # sqlalchemy (ORM)
+    if sqlalchemy_engine is not None and db_libraries is not None and "sqlalchemy" not in db_libraries:
+        logger.warning(
+            "sqlalchemy_engine was provided but 'sqlalchemy' is not in db_libraries; "
+            "engine will not be instrumented"
+        )
     if db_libraries is None or "sqlalchemy" in db_libraries:
         try:
             from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
 
-            SQLAlchemyInstrumentor().instrument()
+            if sqlalchemy_engine is not None:
+                # Validate engine type before passing to instrumentor
+                try:
+                    from sqlalchemy.engine import Engine as _SAEngine
+                except ImportError:
+                    raise TypeError(
+                        "sqlalchemy_engine was provided but sqlalchemy is not installed"
+                    )
+                if not isinstance(sqlalchemy_engine, _SAEngine):
+                    raise TypeError(
+                        f"sqlalchemy_engine must be a sqlalchemy.engine.Engine instance, "
+                        f"got {type(sqlalchemy_engine).__name__}"
+                    )
+                # Instrument the existing engine directly (registers event listeners)
+                SQLAlchemyInstrumentor().instrument(engine=sqlalchemy_engine)
+                logger.info("Instrumented: sqlalchemy (existing engine)")
+            else:
+                # Patch create_engine() for future engines only
+                SQLAlchemyInstrumentor().instrument()
+                logger.info("Instrumented: sqlalchemy (future engines)")
             instrumented.append("sqlalchemy")
-            logger.info("Instrumented: sqlalchemy")
         except ImportError:
             logger.debug("sqlalchemy instrumentation not available")
 

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/openbox/worker.py

@@ -57,6 +57,7 @@ def create_openbox_worker(
     # Database instrumentation
     instrument_databases: bool = True,
     db_libraries: Optional[set] = None,
+    sqlalchemy_engine: Optional[Any] = None,
     # File I/O instrumentation
     instrument_file_io: bool = False,
     # Standard Worker options
@@ -117,6 +118,10 @@ def create_openbox_worker(
         db_libraries: Set of database libraries to instrument (None = all available).
                       Valid values: "psycopg2", "asyncpg", "mysql", "pymysql",
                       "pymongo", "redis", "sqlalchemy"
+        sqlalchemy_engine: SQLAlchemy Engine instance to instrument. Pass this when
+                          the engine is created before create_openbox_worker() runs
+                          (e.g., at module import time). This ensures query-level
+                          instrumentation works on pre-existing engines.
 
         # File I/O instrumentation
         instrument_file_io: Instrument file I/O operations (default: False)
@@ -171,6 +176,7 @@ def create_openbox_worker(
         instrument_databases=instrument_databases,
         db_libraries=db_libraries,
         instrument_file_io=instrument_file_io,
+        sqlalchemy_engine=sqlalchemy_engine,
     )
 
     # 4. Create governance config

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openbox-temporal-sdk-python"
-version = "1.0.1"
+version = "1.0.2"
 description = "OpenBox SDK - Governance and observability for Temporal workflows"
 authors = [
     { name = "OpenBox Team", email = "tino@openbox.ai" },

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/tests/test_otel_setup.py

@@ -462,7 +462,7 @@ class TestSetupOpentelemetryForGovernance:
                         instrument_file_io=False,
                     )
 
-                    mock_db_setup.assert_called_once_with({"psycopg2"})
+                    mock_db_setup.assert_called_once_with({"psycopg2"}, None)
 
     def test_calls_setup_file_io_instrumentation_when_enabled(self, mock_span_processor):
         """Should call setup_file_io_instrumentation when instrument_file_io=True."""
@@ -868,7 +868,7 @@ class TestSetupDatabaseInstrumentation:
             assert "redis" in result
 
     def test_instruments_sqlalchemy(self):
-        """Should instrument sqlalchemy library."""
+        """Should instrument sqlalchemy library (future engines path)."""
         from openbox.otel_setup import setup_database_instrumentation
 
         with patch('opentelemetry.instrumentation.sqlalchemy.SQLAlchemyInstrumentor') as mock_sqlalchemy:
@@ -877,9 +877,126 @@ class TestSetupDatabaseInstrumentation:
 
             result = setup_database_instrumentation(db_libraries={"sqlalchemy"})
 
-            mock_instance.instrument.assert_called_once()
+            mock_instance.instrument.assert_called_once_with()
             assert "sqlalchemy" in result
 
+    def test_instruments_sqlalchemy_with_existing_engine(self):
+        """Should instrument sqlalchemy with existing engine when provided."""
+        from openbox.otel_setup import setup_database_instrumentation
+
+        with patch('opentelemetry.instrumentation.sqlalchemy.SQLAlchemyInstrumentor') as mock_sqlalchemy:
+            mock_instance = MagicMock()
+            mock_sqlalchemy.return_value = mock_instance
+
+            # Create a mock that passes the isinstance check
+            with patch('openbox.otel_setup.setup_database_instrumentation') as _:
+                pass  # just to show we need a real-ish engine
+
+            # Use a mock Engine that passes isinstance check
+            from unittest.mock import create_autospec
+            try:
+                from sqlalchemy.engine import Engine
+                mock_engine = create_autospec(Engine, instance=True)
+            except ImportError:
+                pytest.skip("sqlalchemy not installed")
+
+            result = setup_database_instrumentation(
+                db_libraries={"sqlalchemy"},
+                sqlalchemy_engine=mock_engine,
+            )
+
+            mock_instance.instrument.assert_called_once_with(engine=mock_engine)
+            assert "sqlalchemy" in result
+
+    def test_sqlalchemy_engine_rejects_non_engine_type(self):
+        """Should raise TypeError when sqlalchemy_engine is not an Engine instance."""
+        from openbox.otel_setup import setup_database_instrumentation
+
+        try:
+            import sqlalchemy  # noqa
+        except ImportError:
+            pytest.skip("sqlalchemy not installed")
+
+        with patch('opentelemetry.instrumentation.sqlalchemy.SQLAlchemyInstrumentor'):
+            with pytest.raises(TypeError, match="must be a sqlalchemy.engine.Engine instance"):
+                setup_database_instrumentation(
+                    db_libraries={"sqlalchemy"},
+                    sqlalchemy_engine="not-an-engine",
+                )
+
+    def test_sqlalchemy_engine_rejects_when_sqlalchemy_not_installed(self):
+        """Should raise TypeError when engine provided but sqlalchemy not installed."""
+        from openbox.otel_setup import setup_database_instrumentation
+
+        with patch('opentelemetry.instrumentation.sqlalchemy.SQLAlchemyInstrumentor'):
+            with patch.dict('sys.modules', {'sqlalchemy': None, 'sqlalchemy.engine': None}):
+                with pytest.raises(TypeError, match="sqlalchemy is not installed"):
+                    setup_database_instrumentation(
+                        db_libraries={"sqlalchemy"},
+                        sqlalchemy_engine=MagicMock(),
+                    )
+
+    def test_warns_when_engine_provided_but_sqlalchemy_not_in_db_libraries(self):
+        """Should warn when sqlalchemy_engine provided but 'sqlalchemy' not in db_libraries."""
+        from openbox.otel_setup import setup_database_instrumentation
+        import logging
+
+        with patch('opentelemetry.instrumentation.psycopg2.Psycopg2Instrumentor') as mock_psycopg2:
+            mock_psycopg2.return_value = MagicMock()
+
+            with patch.object(logging.getLogger('openbox.otel_setup'), 'warning') as mock_warn:
+                setup_database_instrumentation(
+                    db_libraries={"psycopg2"},
+                    sqlalchemy_engine=MagicMock(),
+                )
+
+                mock_warn.assert_called_once()
+                assert "not in db_libraries" in mock_warn.call_args[0][0]
+
+    def test_warns_when_engine_provided_but_databases_disabled(self, mock_span_processor):
+        """Should warn when sqlalchemy_engine provided but instrument_databases=False."""
+        import openbox.otel_setup as otel_setup
+        import logging
+
+        with patch.object(otel_setup, 'setup_httpx_body_capture'):
+            with patch('opentelemetry.trace.get_tracer_provider') as mock_get_provider:
+                mock_provider = MagicMock()
+                mock_get_provider.return_value = mock_provider
+
+                with patch.object(logging.getLogger('openbox.otel_setup'), 'warning') as mock_warn:
+                    otel_setup.setup_opentelemetry_for_governance(
+                        span_processor=mock_span_processor,
+                        instrument_databases=False,
+                        instrument_file_io=False,
+                        sqlalchemy_engine=MagicMock(),
+                    )
+
+                    mock_warn.assert_called_once()
+                    assert "instrument_databases=False" in mock_warn.call_args[0][0]
+
+    def test_sqlalchemy_engine_passthrough_from_setup_governance(self, mock_span_processor):
+        """Should pass sqlalchemy_engine through to setup_database_instrumentation."""
+        import openbox.otel_setup as otel_setup
+
+        mock_engine = MagicMock()
+
+        with patch.object(otel_setup, 'setup_httpx_body_capture'):
+            with patch.object(otel_setup, 'setup_database_instrumentation') as mock_db_setup:
+                mock_db_setup.return_value = ["sqlalchemy"]
+                with patch('opentelemetry.trace.get_tracer_provider') as mock_get_provider:
+                    mock_provider = MagicMock()
+                    mock_get_provider.return_value = mock_provider
+
+                    otel_setup.setup_opentelemetry_for_governance(
+                        span_processor=mock_span_processor,
+                        instrument_databases=True,
+                        db_libraries={"sqlalchemy"},
+                        instrument_file_io=False,
+                        sqlalchemy_engine=mock_engine,
+                    )
+
+                    mock_db_setup.assert_called_once_with({"sqlalchemy"}, mock_engine)
+
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # Tests for uninstrument_all()

{openbox_temporal_sdk_python-1.0.1 → openbox_temporal_sdk_python-1.0.2}/tests/test_worker.py

@@ -135,6 +135,7 @@ class TestCreateOpenboxWorkerWithConfig:
             instrument_databases=True,
             db_libraries={"psycopg2", "redis"},
             instrument_file_io=True,
+            sqlalchemy_engine=None,
         )
 
     @patch("openbox.worker.Worker")
@@ -1380,6 +1381,78 @@ class TestConfigurationOptions:
         call_kwargs = mock_setup_otel.call_args[1]
         assert call_kwargs["instrument_file_io"] is True
 
+    @patch("openbox.worker.Worker")
+    @patch("openbox.worker.validate_api_key")
+    @patch("openbox.worker.WorkflowSpanProcessor")
+    @patch("openbox.worker.GovernanceConfig")
+    @patch("openbox.otel_setup.setup_opentelemetry_for_governance")
+    @patch("openbox.workflow_interceptor.GovernanceInterceptor")
+    @patch("openbox.activity_interceptor.ActivityGovernanceInterceptor")
+    @patch("openbox.activities.send_governance_event")
+    def test_sqlalchemy_engine_passed_to_setup(
+        self,
+        mock_send_governance_event,
+        mock_activity_interceptor,
+        mock_governance_interceptor,
+        mock_setup_otel,
+        mock_governance_config,
+        mock_span_processor_class,
+        mock_validate_api_key,
+        mock_worker_class,
+    ):
+        """Test sqlalchemy_engine is passed to setup_opentelemetry_for_governance."""
+        from openbox.worker import create_openbox_worker
+
+        mock_client = Mock()
+        mock_engine = Mock()
+
+        create_openbox_worker(
+            client=mock_client,
+            task_queue="test-queue",
+            openbox_url="http://localhost:8086",
+            openbox_api_key="obx_test_key123",
+            sqlalchemy_engine=mock_engine,
+        )
+
+        mock_setup_otel.assert_called_once()
+        call_kwargs = mock_setup_otel.call_args[1]
+        assert call_kwargs["sqlalchemy_engine"] is mock_engine
+
+    @patch("openbox.worker.Worker")
+    @patch("openbox.worker.validate_api_key")
+    @patch("openbox.worker.WorkflowSpanProcessor")
+    @patch("openbox.worker.GovernanceConfig")
+    @patch("openbox.otel_setup.setup_opentelemetry_for_governance")
+    @patch("openbox.workflow_interceptor.GovernanceInterceptor")
+    @patch("openbox.activity_interceptor.ActivityGovernanceInterceptor")
+    @patch("openbox.activities.send_governance_event")
+    def test_sqlalchemy_engine_defaults_to_none(
+        self,
+        mock_send_governance_event,
+        mock_activity_interceptor,
+        mock_governance_interceptor,
+        mock_setup_otel,
+        mock_governance_config,
+        mock_span_processor_class,
+        mock_validate_api_key,
+        mock_worker_class,
+    ):
+        """Test sqlalchemy_engine defaults to None when not provided."""
+        from openbox.worker import create_openbox_worker
+
+        mock_client = Mock()
+
+        create_openbox_worker(
+            client=mock_client,
+            task_queue="test-queue",
+            openbox_url="http://localhost:8086",
+            openbox_api_key="obx_test_key123",
+        )
+
+        mock_setup_otel.assert_called_once()
+        call_kwargs = mock_setup_otel.call_args[1]
+        assert call_kwargs["sqlalchemy_engine"] is None
+
 
 # ===============================================================================
 # Print Output Tests