dex-python-sdk 0.0.1__tar.gz → 0.1.1__tar.gz

dex_python_sdk-0.1.1/LEGACY_NOTICES.md

@@ -0,0 +1,61 @@
+# Legacy and third-party notices
+
+The Super Durable Source License 1.0 applies only to material owned or
+licensable by Super Durable, Inc. It does not replace the licenses below.
+
+## Legacy cutoff
+
+The complete repository snapshot at commit
+`1a61670238cbdc8f2a0a6dd78cc5668fb014f283`, including both parents of that
+merge commit, is Legacy Materials. Later copies and adaptations retain the
+applicable legacy license for their legacy portions.
+
+At the cutoff, the principal directory licenses were:
+
+| Cutoff path | Legacy license |
+| --- | --- |
+| `server/` | MIT |
+| `sdk-go/` | Apache License 2.0 |
+| `sdk-java/` | Apache License 2.0 |
+| `sdk-python/` | Apache License 2.0 |
+| `protos/` | MIT or Apache License 2.0, at the recipient's option |
+| `samples-go/` | MIT |
+| `samples-java/` | Apache License 2.0 |
+| `samples-python/` | Apache License 2.0 |
+
+The MIT and Apache License 2.0 texts are in `LICENSES/`. Historical copyright
+and attribution notices remain authoritative and must be preserved. Git history
+identifies the exact material present at the cutoff.
+
+## Excluded directories
+
+This relicensing does not cover `docs/` or `examples/`.
+
+- `examples/go/` remains under its existing MIT License.
+- `examples/java/` and `examples/python/` remain under their existing Apache
+  License 2.0 terms.
+- `docs/` retains its legacy copyright and licensing status. This repository
+  makes no new license grant for that directory.
+
+## Existing third-party notices
+
+Some source files retain notices naming Cadence workflow OSS organization,
+Uber Technologies, Inc., Indeed, Inc., individual contributors, or other
+holders. Those notices and their accompanying licenses remain in force.
+
+Dependencies not copied into this repository remain governed by the license
+distributed with each dependency.
+
+## IWF Java SDK integration fixtures
+
+The workflow and integration-test fixtures under these paths are adaptations
+or translations of the `indeedeng/iwf-java-sdk` integration suite at commit
+`8fa04457c0abcc4473300f17ea0a033d8f93ed88`:
+
+- `sdk-java/src/test/java/io/superdurable/dex/integ/`
+- `sdk-python/tests/integ/`
+- `sdk-typescript/test/integ/`
+
+The upstream portions remain licensed under the Apache License 2.0. Super
+Durable modifications are licensed under the Super Durable Source License 1.0.
+The Apache License 2.0 text is in `LICENSES/Apache-2.0.txt`.

dex_python_sdk-0.1.1/LICENSE

@@ -0,0 +1,192 @@
+Super Durable Source License 1.0
+
+Copyright (c) 2026 Super Durable, Inc.
+
+Acceptance
+
+This agreement governs the Software made available by Super Durable, Inc.
+("Licensor"). By copying, modifying, distributing, or using the Software, You
+accept this agreement. If You act for an entity, You represent that You have
+authority to bind that entity, and "You" means that entity.
+
+License Grant
+
+Subject to this agreement, Licensor grants You a non-exclusive, worldwide,
+non-transferable, non-sublicensable license to copy and modify the Software and
+to use it for Non-Production Use.
+
+Licensor also grants You a license to make Production Use when either:
+
+1. You are a Qualified User; or
+2. You have a current Subscription authorizing that Production Use.
+
+If You cease to be a Qualified User, You may continue the same Production Use
+for ninety (90) days after the end of the first fiscal year for which Your
+Consolidated Annual Revenue exceeds the Revenue Threshold. After that grace
+period, continued Production Use requires a Subscription.
+
+The licenses in this section include the right to make, have made, use, sell,
+offer for sale, and import the Software only under patent claims Licensor can
+license that are necessarily infringed by the Software as provided by
+Licensor. If You bring a written patent infringement claim concerning the
+Software, this patent license terminates immediately.
+
+Applications and Client Components
+
+While otherwise complying with this agreement, You may distribute Client
+Components, in source or object form, solely as an embedded or bundled part of
+an Application. The Application must have a primary purpose other than
+providing the Software, a Competitive Product, or a hosted Dex-compatible
+service.
+
+A recipient may run an Application containing Client Components without a
+separate Subscription. This exception does not permit the recipient to extract,
+modify, redistribute, or use Client Components independently, or to deploy or
+operate other Software. A person that develops or operates an Application is
+still subject to the Production Use and Revenue Threshold requirements.
+
+Competitive Use
+
+You may not make Competitive Use without a separate written commercial license
+from Licensor. The Revenue Threshold, Qualified User status, grace period, and
+Application exception do not authorize Competitive Use.
+
+Source Collaboration
+
+You may publicly host a source fork or distribute patches solely for
+evaluation, internal development, or contribution to Licensor, provided You:
+
+1. do not make Production Use or Competitive Use through that distribution;
+2. preserve this agreement and all copyright, attribution, and license notices;
+3. identify files You modified; and
+4. apply this agreement to Your modifications to the Software.
+
+No other redistribution of the Software or a Modified Version is permitted
+except under the Application exception or a Subscription.
+
+Legacy and Third-Party Materials
+
+This agreement applies only to the Software and modifications owned or
+licensable by Licensor. It does not replace or restrict any license applying to
+Legacy Materials or Third-Party Materials. Those materials remain governed by
+their respective licenses. Their notices and license texts must be preserved.
+See LEGACY_NOTICES.md and accompanying third-party notices.
+
+Commercial Licenses
+
+A Subscription or other written commercial agreement may grant additional
+rights. If its terms conflict with this agreement, the commercial agreement
+controls only for the Software, use, and period it expressly covers. Contact
+licensing@superdurable.io for a Subscription or Competitive Use license.
+
+Restrictions and Obligations
+
+You must not:
+
+1. remove or obscure copyright, license, attribution, or trademark notices;
+2. represent that Licensor endorses You or Your products;
+3. use Licensor's names, marks, or logos except to accurately identify the
+   origin of the Software; or
+4. enable another person to exercise rights that this agreement does not grant.
+
+You are responsible for Your affiliates, contractors, and agents that use the
+Software on Your behalf. You must comply with applicable export, import, and
+sanctions laws.
+
+Termination
+
+Your rights terminate automatically if You breach this agreement. If the breach
+is capable of cure and is neither intentional nor repeated, Your rights are
+reinstated retroactively when You cure it within fifteen (15) days after the
+breach. Intentional or repeated breaches permanently terminate Your rights
+unless Licensor agrees otherwise in writing.
+
+No Other Rights
+
+Except for rights expressly granted here, Licensor reserves all rights. This
+agreement grants no trademark rights and does not require Licensor to provide
+support, maintenance, updates, or a Subscription.
+
+Disclaimer
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS" AND
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT,
+ACCURACY, OR UNINTERRUPTED OR ERROR-FREE OPERATION.
+
+Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, LICENSOR WILL NOT BE LIABLE FOR ANY
+INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES,
+OR FOR LOST PROFITS, REVENUE, DATA, OR BUSINESS INTERRUPTION. LICENSOR'S TOTAL
+LIABILITY ARISING FROM THIS AGREEMENT OR THE SOFTWARE WILL NOT EXCEED ONE
+HUNDRED U.S. DOLLARS (US$100), REGARDLESS OF THE LEGAL THEORY AND EVEN IF
+LICENSOR WAS ADVISED THAT SUCH DAMAGES WERE POSSIBLE.
+
+Governing Law
+
+Delaware law and applicable United States federal law govern this agreement,
+without regard to conflict-of-law rules. The state and federal courts located
+in Delaware have exclusive jurisdiction. The United Nations Convention on
+Contracts for the International Sale of Goods does not apply.
+
+Definitions
+
+"Affiliate" means an entity that directly or indirectly controls, is controlled
+by, or is under common control with You. "Control" means ownership of more than
+fifty percent (50%) of voting interests or the power to direct management.
+
+"Application" means software developed for a business or end-user purpose whose
+primary purpose is not to provide the Software or a Competitive Product.
+
+"Client Components" means the SDK and protocol-definition portions of the
+Software intended to be integrated into Applications.
+
+"Competitive Product" means software or a service whose primary purpose is to
+replace or provide substantially similar functionality to a Dex server, Dex
+SDK, Dex command-line product, Dex web product, or a hosted Dex-compatible
+service. An Application, connector, plug-in, or adapter that merely interoperates
+with Dex is not a Competitive Product.
+
+"Competitive Use" means developing, distributing, offering, or operating a
+Competitive Product for any third party.
+
+"Consolidated Annual Revenue" means the gross revenue of You and all Affiliates,
+without double counting intercompany transactions, for the most recently
+completed fiscal year, as determined under consistently applied GAAP or IFRS.
+Non-U.S.-dollar revenue is converted to U.S. dollars using the exchange rate
+used in the applicable consolidated financial statements. If You have no
+completed fiscal year, use a good-faith annualization of revenue since formation.
+
+"Legacy Cutoff" means Git commit
+1a61670238cbdc8f2a0a6dd78cc5668fb014f283 in the Software's repository.
+
+"Legacy Materials" means material contained in the complete repository snapshot
+at the Legacy Cutoff, including material reachable through either parent of that
+merge commit, and later copies or adaptations of that material, to the extent
+governed by a license other than this agreement.
+
+"Modified Version" means any modification or derivative work of the Software.
+
+"Non-Production Use" means design, prototyping, evaluation, testing, or
+development that does not serve live end users, process live business workloads,
+or support production operations.
+
+"Production Use" means any use other than Non-Production Use.
+
+"Qualified User" means You when Your Consolidated Annual Revenue does not exceed
+the Revenue Threshold and You are not making Competitive Use.
+
+"Revenue Threshold" means ten million U.S. dollars (US$10,000,000).
+
+"Software" means files in this repository that include or refer to this
+agreement, in source or object form, excluding the docs/ and examples/
+directories, Legacy Materials, and Third-Party Materials.
+
+"Subscription" means a current written commercial subscription or license from
+Licensor that authorizes the applicable Production Use.
+
+"Third-Party Materials" means material owned by a third party and provided under
+separate license terms.
+
+"You" means the individual or legal entity accepting this agreement.

dex_python_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: dex-python-sdk
+Version: 0.1.1
+Requires-Dist: grpcio>=1.83.0
+Requires-Dist: grpcio-status>=1.83.0
+Requires-Dist: protobuf>=7.35.1
+License-File: LICENSE
+License-File: LEGACY_NOTICES.md
+Summary: Python SDK for the Dex workflow engine
+Author: Super Durable
+License-Expression: LicenseRef-Super-Durable-1.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/superdurable/dex/tree/main/sdk-python
+Project-URL: Repository, https://github.com/superdurable/dex
+
+
+# Dex SDK for Python
+
+Python SDK for [Dex workflow engine](https://github.com/superdurable/dex)
+
+## New user contracts
+
+The rewrite targets Python 3.11+ and exposes strongly typed workflow contracts
+from `dex`. This phase includes definitions, attributes, channels, waits,
+decisions, codecs, registry validation, synchronous client calls, and synchronous
+worker handlers. Python owns its gRPC Client and Worker transport;
+the shared Rust Core is used only for BlobCache.
+
+```python
+from datetime import timedelta
+
+import dex
+
+counter = dex.Attribute("counter", int)
+counters_by_region = dex.AttributeMap("counters-by-region", int)
+
+class Run(dex.Step[str]):
+    def wait_for(
+        self, context: dex.Context, input: str
+    ) -> dex.Wait:
+        return dex.Wait.all_of(
+            dex.Timer.by_duration(timedelta(seconds=1))
+        )
+
+    def execute(
+        self, context: dex.Context, input: str
+    ) -> dex.StepDecision:
+        return dex.graceful_complete(input)
+
+class CounterFlow(dex.Flow[str]):
+    run = Run()
+
+    def get_flow_type(self) -> str:
+        return "Counter"
+
+    def get_steps(self) -> dex.StepList[str]:
+        return dex.StepList.start_step(self.run)
+
+    def get_persistence_schema(self) -> dex.PersistenceSchema:
+        return dex.PersistenceSchema.of(counter, counters_by_region)
+
+    @dex.rpc(name="Increment")
+    def increment(
+        self, context: dex.Context, input: int
+    ) -> dex.RPCResult[int]:
+        return dex.RPCResult(input + 1)
+
+flow = CounterFlow()
+registry = dex.Registry((flow,))
+```
+
+Registry derives codecs from declared Python types and handler annotations.
+Built-in scalar types and dataclasses need no codec arguments. Register an
+explicit codec only for a custom encoding or a type Registry cannot derive.
+`PersistenceSchema.of(...)` accepts attributes and channels together and
+partitions them by definition type.
+
+Initial attributes retain their value types without a public wrapper class:
+
+```python
+options = (
+    dex.StartFlowOptions()
+    .with_attribute(counter, 1)
+    .with_attribute(counters_by_region, "us-west", 1)
+)
+```
+
+```
+pip install dex-python-sdk==0.1.0
+```
+
+See [samples](../examples/python) for use case examples.
+
+## Requirements
+
+- Python 3.11+
+- [Dex server](https://github.com/superdurable/dex#how-to-use)
+
+## Concepts
+
+Applications implement two generic interfaces from [`dex`](dex/):
+
+- `Flow[START_INPUT]` returns `StepList.start_step(...)`, followed by optional
+  `.other_steps(...)`, from one `get_steps()` method. The `StepList` generic
+  binds the Flow input to the starting Step input. Use `StepList.empty()` when
+  a Flow has no Steps.
+- `Step[INPUT]` implements `execute` and optionally `wait_for`. The default
+  Worker path requires synchronous handlers. With `AsyncWorker` and
+  `Registry(..., allow_async_handlers=True)`, handlers may be `async def` and
+  `await` an `AsyncClient`.
+
+`StepOptions.wait_for_method_timeout` and `execute_method_timeout` bound the
+two handler calls. Timer and channel conditions determine how long a Step waits.
+
+`Registry` validates every Flow, Step, RPC signature, durable name, lock, and
+codec before Client or Worker startup. `Client` methods use these typed objects
+instead of raw Flow, Step, or RPC strings.
+
+### Sync vs asyncio
+
+- **Sync (default):** `Client` and `Worker` use blocking gRPC and a thread-pool
+  Worker. Blocking `Client` calls inside `Step.execute` are safe (one pool
+  thread is occupied; other RPCs still run).
+- **Asyncio:** `AsyncClient` and `AsyncWorker` use `grpc.aio`. Use
+  `Registry(..., allow_async_handlers=True)` when Steps/RPCs are coroutines.
+  Inside async `execute`, inject `AsyncClient` — do not call sync `Client` on
+  the Worker event loop. Sync `Worker` still rejects coroutine handlers at
+  registry construction unless `allow_async_handlers=True` (and even then the
+  sync Worker dispatcher rejects awaitable return values).
+
+Integration scenarios live under
+[`tests/integ`](tests/integ/README.md). They exercise the same workflows,
+client operations, and assertions as the Java suite against an isolated
+`dexcli dev` environment.
+
+## Implementation status
+
+The strongly typed contracts, registry, synchronous Client/Worker, optional
+`AsyncClient`/`AsyncWorker` (`grpc.aio`), and Rust-backed BlobCache are
+implemented. Python owns its gRPC transport; the native bridge is limited to
+the shared BlobCache. Design notes:
+[`docs/design/plan/python-sdk-async-apis.md`](../docs/design/plan/python-sdk-async-apis.md).
+
+## Running dex-server locally
+
+### Option 1: use docker compose
+See [dex README](https://github.com/superdurable/dex#using-docker-image--docker-compose)
+
+### Option 2: VSCode Dev Container
+
+Dev Container is an easy way to get dex-server running locally. Follow these steps to launch a dev container:
+- Install Docker, VSCode, and [VSCode Dev Container plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+- Open the project in VSCode.
+    ```bash
+    cd dex-python-sdk
+    code .
+    ```
+- Launch the Remote-Containers: Reopen in Container command from Command Palette (Ctrl + Shift + P). You can also click in the bottom left corner to access the remote container menu.
+- Once the dev container starts, dex-server will be listening on port 8801.
+
+## How To Contribute
+
+This project uses [uv](https://docs.astral.sh/uv/) for Python versions,
+dependencies, virtual environments, locking, building, and publishing.
+
+To install requirements:
+
+```bash
+uv sync --locked
+```
+
+Run the complete Python SDK integration suite with an isolated Dex development
+environment:
+
+```bash
+./run-integration-tests.sh
+```
+
+### Measure integration coverage
+
+Run the same integration suite with Python source coverage:
+
+```bash
+./run-integration-tests.sh --coverage
+```
+
+Only the integration scenarios contribute execution data, and only production
+Python modules under `dex` are measured. Generated protobuf modules under
+`dex/dexpb` are excluded. The
+terminal report lists uncovered line ranges. The browser report starts at
+`coverage/html/index.html`; `coverage/coverage.xml` and `coverage/lcov.info`
+are also generated.
+
+CI uploads LCOV to Codecov with GitHub OIDC under the
+`sdk-python-integration` flag and retains the full report as the
+`sdk-python-integration-coverage` Actions artifact.
+
+#### Update IDL
+
+Edit [`protos/dex.proto`](../protos/dex.proto). Rename catalog: [`docs/design/idl-renames.md`](../docs/design/idl-renames.md).
+
+#### Generate stubs from IDL
+
+```bash
+make -C ../protos proto-python
+```
+
+Checked-in Python stubs land in `dex/dexpb/`.
+#### Linting
+
+To run linting for this project:
+
+```bash
+uv run --frozen pre-commit run --show-diff-on-failure --color=always --all-files
+```
+
+## Code of Conduct
+This project is governed by the [Contributor Covenant v 1.4.1](CODE_OF_CONDUCT.md). (Review the Code of Conduct and remove this sentence before publishing your project.)
+
+## Publishing to PyPI
+
+1. Optionally run **Publish Python SDK to PyPI** via workflow_dispatch with a version and
+   `publish=false` to validate all distributions without uploading.
+2. Create a GitHub Release with tag `sdk-python/vX.Y.Z` (for example `sdk-python/v0.1.0`).
+   CI stamps that version into `pyproject.toml` for the build (same idea as the TypeScript
+   SDK release), then builds and smoke-tests Linux x86_64/ARM64, macOS x86_64/ARM64, and
+   Windows x86_64 wheels, verifies the source distribution, and publishes with `PYPI_TOKEN`.
+3. After publishing, bump the committed `pyproject.toml` / docs install line when you want
+   the repo tip to reflect the released version.
+
+A manual run publishes only from `main`, and only when `publish` is explicitly selected.
+The dispatch `version` input is stamped the same way as a release tag.
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md#releases-monorepo-tags) for monorepo tag conventions.
+
+## License
+
+[Super Durable Source License 1.0](LICENSE), with legacy portions under their
+original terms as described in [LEGACY_NOTICES.md](LEGACY_NOTICES.md).
+