stabilize 0.13.9__tar.gz

stabilize-0.13.9/.env.example

@@ -0,0 +1,19 @@
+# Stabilize Environment Configuration
+
+# Database Configuration
+# PostgreSQL: postgresql://user:pass@localhost:5432/stabilize
+# SQLite: sqlite:///./stabilize.db
+MG_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/stabilize
+
+# Resilience Configuration (optional, defaults shown)
+
+# Bulkhead settings per task type - max concurrent executions
+STABILIZE_BULKHEAD_SHELL_MAX_CONCURRENT=5
+STABILIZE_BULKHEAD_PYTHON_MAX_CONCURRENT=3
+STABILIZE_BULKHEAD_HTTP_MAX_CONCURRENT=10
+STABILIZE_BULKHEAD_DOCKER_MAX_CONCURRENT=3
+STABILIZE_BULKHEAD_SSH_MAX_CONCURRENT=5
+
+# Circuit breaker settings
+STABILIZE_CIRCUIT_FAILURE_THRESHOLD=0.5
+STABILIZE_CIRCUIT_COOLDOWN_SECONDS=30

stabilize-0.13.9/.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+.venv
+venv
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+S3_IMPLEMENTATION_PLAN.md
+COMPLETE_S3_INTEGRATION.sh
+data/
+test_table*
+.env
+next-steps.md
+CERTIFICATION_AUDIT_REPORT.md
+
+*.md

stabilize-0.13.9/.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py

stabilize-0.13.9/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Farshid Ashouri
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

stabilize-0.13.9/Makefile

@@ -0,0 +1,94 @@
+# Stabilize Makefile
+# Run tests on SQLite and PostgreSQL backends
+
+.PHONY: help test golden-tests golden-tests-sqlite golden-tests-postgres test-all lint type-check
+
+# Default target
+help:
+	@echo "Stabilize Test Commands:"
+	@echo ""
+	@echo "  make test                  - Run all unit tests (both backends)"
+	@echo "  make test-sqlite           - Run unit tests on SQLite only"
+	@echo "  make test-postgres         - Run unit tests on PostgreSQL only (requires Docker)"
+	@echo ""
+	@echo "  make golden-tests          - Run golden standard tests (both backends)"
+	@echo "  make golden-tests-sqlite   - Run golden tests on SQLite only"
+	@echo "  make golden-tests-postgres - Run golden tests on PostgreSQL only (requires Docker)"
+	@echo ""
+	@echo "  make test-all              - Run all tests including golden standards"
+	@echo ""
+	@echo "  make lint                  - Run ruff linter"
+	@echo "  make type-check            - Run mypy type checker"
+	@echo "  make check                 - Run lint + type-check + tests"
+	@echo ""
+
+# =============================================================================
+# Unit Tests
+# =============================================================================
+
+# Run all unit tests (both backends)
+test:
+	python -m pytest tests/ -v --tb=short
+
+# Run unit tests on SQLite only
+test-sqlite:
+	python -m pytest tests/ -v --tb=short -k "sqlite"
+
+# Run unit tests on PostgreSQL only (requires Docker)
+test-postgres:
+	python -m pytest tests/ -v --tb=short -k "postgres"
+
+# =============================================================================
+# Golden Standard Tests
+# =============================================================================
+
+# Run golden standard tests on both backends
+golden-tests: golden-tests-sqlite golden-tests-postgres
+
+# Run golden tests on SQLite only (fast, no Docker required)
+golden-tests-sqlite:
+	python -m pytest golden_standard_tests/ -v --tb=short -k "sqlite"
+
+# Run golden tests on PostgreSQL only (requires Docker)
+golden-tests-postgres:
+	python -m pytest golden_standard_tests/ -v --tb=short -k "postgres"
+
+# =============================================================================
+# Combined Tests
+# =============================================================================
+
+# Run all tests including golden standards
+test-all: test golden-tests
+
+# =============================================================================
+# Code Quality
+# =============================================================================
+
+# Run ruff linter
+lint:
+	ruff check src/ tests/ golden_standard_tests/
+
+# Run ruff linter with auto-fix
+lint-fix:
+	ruff check src/ tests/ golden_standard_tests/ --fix
+
+# Run mypy type checker
+type-check:
+	mypy src/
+
+# Run all quality checks
+check: lint type-check test
+
+# =============================================================================
+# Development Helpers
+# =============================================================================
+
+# Install development dependencies
+install-dev:
+	pip install -e ".[dev]"
+
+# Clean up cache files
+clean:
+	rm -rf __pycache__ .pytest_cache .mypy_cache .ruff_cache
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true

stabilize-0.13.9/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: stabilize
+Version: 0.13.9
+Summary: Highway Workflow Engine - Stabilize execution layer
+Project-URL: Homepage, https://github.com/rodmena-limited/stabilize
+Project-URL: Repository, https://github.com/rodmena-limited/stabilize
+Project-URL: Issues, https://github.com/rodmena-limited/stabilize/issues
+Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: dag,orchestration,pipeline,task-runner,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: bulkman>=0.1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-ulid>=2.0
+Requires-Dist: resilient-circuit>=0.1.0
+Provides-Extra: all
+Requires-Dist: migretti>=0.3; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.20; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
+Requires-Dist: psycopg[pool]>=3.0; extra == 'all'
+Requires-Dist: structlog>=24.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: migretti>=0.3; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: opentelemetry-api>=1.20; extra == 'dev'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'dev'
+Requires-Dist: psycopg[pool]>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: structlog>=24.0; extra == 'dev'
+Requires-Dist: testcontainers>=4.0; extra == 'dev'
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.20; extra == 'observability'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'observability'
+Requires-Dist: structlog>=24.0; extra == 'observability'
+Provides-Extra: postgres
+Requires-Dist: migretti>=0.3; extra == 'postgres'
+Requires-Dist: psycopg[pool]>=3.0; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# Stabilize
+
+A lightweight full featured Python workflow execution engine with DAG-based stage orchestration.
+
+## Requirements
+
+- Python 3.11+
+- SQLite (included) or PostgreSQL 12+
+
+## Installation
+
+```bash
+pip install stabilize            # SQLite support only
+pip install stabilize[postgres]  # PostgreSQL support
+pip install stabilize[all]       # All features
+```
+
+## Features
+
+- Message-driven DAG execution engine
+- Parallel and sequential stage execution
+- Synthetic stages (before/after/onFailure)
+- PostgreSQL and SQLite persistence
+- Pluggable task system
+- Retry and timeout support
+
+## Quick Start
+
+```python
+from stabilize import (
+    Workflow, StageExecution, TaskExecution,
+    SqliteWorkflowStore, SqliteQueue, QueueProcessor, Orchestrator,
+    Task, TaskResult, TaskRegistry,
+    # All 11 handlers are required
+    StartWorkflowHandler, StartWaitingWorkflowsHandler, StartStageHandler,
+    SkipStageHandler, CancelStageHandler, ContinueParentStageHandler,
+    StartTaskHandler, RunTaskHandler, CompleteTaskHandler,
+    CompleteStageHandler, CompleteWorkflowHandler,
+)
+
+# Define a custom task
+class HelloTask(Task):
+    def execute(self, stage: StageExecution) -> TaskResult:
+        name = stage.context.get("name", "World")
+        return TaskResult.success(outputs={"greeting": f"Hello, {name}!"})
+
+# Create a workflow
+workflow = Workflow.create(
+    application="my-app",
+    name="Hello Workflow",
+    stages=[
+        StageExecution(
+            ref_id="1",
+            type="hello",
+            name="Say Hello",
+            tasks=[
+                TaskExecution.create(
+                    name="Hello Task",
+                    implementing_class="hello",
+                    stage_start=True,
+                    stage_end=True,
+                ),
+            ],
+            context={"name": "Stabilize"},
+        ),
+    ],
+)
+
+# Setup persistence and queue
+store = SqliteWorkflowStore("sqlite:///:memory:", create_tables=True)
+queue = SqliteQueue("sqlite:///:memory:")
+queue._create_table()
+
+# Register tasks
+registry = TaskRegistry()
+registry.register("hello", HelloTask)
+
+# Create processor and register handlers
+processor = QueueProcessor(queue)
+for handler in [
+    StartWorkflowHandler(queue, store),
+    StartWaitingWorkflowsHandler(queue, store),
+    StartStageHandler(queue, store),
+    SkipStageHandler(queue, store),
+    CancelStageHandler(queue, store),
+    ContinueParentStageHandler(queue, store),
+    StartTaskHandler(queue, store, registry),
+    RunTaskHandler(queue, store, registry),
+    CompleteTaskHandler(queue, store),
+    CompleteStageHandler(queue, store),
+    CompleteWorkflowHandler(queue, store),
+]:
+    processor.register_handler(handler)
+
+orchestrator = Orchestrator(queue)
+
+# Run workflow
+store.store(workflow)
+orchestrator.start(workflow)
+processor.process_all(timeout=10.0)
+
+# Check result
+result = store.retrieve(workflow.id)
+print(f"Status: {result.status}")  # WorkflowStatus.SUCCEEDED
+print(f"Output: {result.stages[0].outputs}")  # {'greeting': 'Hello, Stabilize!'}
+```
+
+## Built-in Tasks
+
+Stabilize includes ready-to-use tasks for common operations:
+
+### ShellTask - Execute Shell Commands
+
+```python
+from stabilize import ShellTask
+
+registry.register("shell", ShellTask)
+
+# Use in stage context
+context = {
+    "command": "npm install && npm test",
+    "cwd": "/app",
+    "timeout": 300,
+    "env": {"NODE_ENV": "test"},
+}
+```
+
+### HTTPTask - HTTP/API Requests
+
+```python
+from stabilize import HTTPTask
+
+registry.register("http", HTTPTask)
+
+# GET with JSON parsing
+context = {"url": "https://api.example.com/data", "parse_json": True}
+
+# POST with JSON body
+context = {"url": "https://api.example.com/users", "method": "POST", "json": {"name": "John"}}
+
+# With authentication
+context = {"url": "https://api.example.com/private", "bearer_token": "token"}
+
+# File upload
+context = {"url": "https://api.example.com/upload", "method": "POST", "upload_file": "/path/to/file.pdf"}
+```
+
+See `examples/` directory for complete examples.
+
+## Parallel Stages
+
+Stages with shared dependencies run in parallel:
+
+```python
+#     Setup
+#    /     \
+#  Test   Lint
+#    \     /
+#    Deploy
+
+workflow = Workflow.create(
+    application="my-app",
+    name="CI/CD Pipeline",
+    stages=[
+        StageExecution(ref_id="setup", type="setup", name="Setup", ...),
+        StageExecution(ref_id="test", type="test", name="Test",
+                      requisite_stage_ref_ids={"setup"}, ...),
+        StageExecution(ref_id="lint", type="lint", name="Lint",
+                      requisite_stage_ref_ids={"setup"}, ...),
+        StageExecution(ref_id="deploy", type="deploy", name="Deploy",
+                      requisite_stage_ref_ids={"test", "lint"}, ...),
+    ],
+)
+```
+
+## Database Setup
+
+### SQLite
+
+No setup required. Schema is created automatically.
+
+### PostgreSQL
+
+Apply migrations using the CLI:
+
+```bash
+# Using mg.yaml in current directory
+stabilize mg-up
+
+# Using database URL
+stabilize mg-up --db-url postgres://user:pass@host:5432/dbname
+
+# Using environment variable
+MG_DATABASE_URL=postgres://user:pass@host:5432/dbname stabilize mg-up
+
+# Check migration status
+stabilize mg-status
+```
+
+Example mg.yaml:
+
+```yaml
+database:
+  host: localhost
+  port: 5432
+  user: postgres
+  password: postgres
+  dbname: stabilize
+```
+
+## CLI Reference
+
+```
+stabilize mg-up [--db-url URL]      Apply pending PostgreSQL migrations
+stabilize mg-status [--db-url URL]  Show migration status
+stabilize monitor [--db-url URL]    Real-time workflow monitoring dashboard
+stabilize prompt                    Output documentation for pipeline code generation
+```
+
+## Running Tests
+
+```bash
+# All tests (requires Docker for PostgreSQL)
+pytest tests/ -v
+
+# SQLite tests only (no Docker)
+pytest tests/ -v -k sqlite
+```
+
+## License
+
+Apache 2.0