requence 0.8.1.dev63__tar.gz → 0.8.1.dev67__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- requence-0.8.1.dev67/PKG-INFO +137 -0
- requence-0.8.1.dev67/README.md +125 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/pyproject.toml +1 -1
- requence-0.8.1.dev67/requence/callbacks/context.py +40 -0
- requence-0.8.1.dev67/requence/callbacks/handler.py +102 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/context.py +13 -1
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/internal_types.py +17 -1
- requence-0.8.1.dev67/requence/requence_callback.py +84 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/__init__.py +296 -18
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/boundary.py +14 -2
- requence-0.8.1.dev67/requence/service/callback_growth.py +218 -0
- requence-0.8.1.dev67/requence/service/durable_callback.py +191 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/surface_handler.py +14 -0
- requence-0.8.1.dev67/requence/store.py +354 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/wire.py +125 -4
- requence-0.8.1.dev67/requence.egg-info/PKG-INFO +137 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/SOURCES.txt +4 -0
- requence-0.8.1.dev67/tests/test_store_parity.py +377 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/tests/test_wire.py +59 -0
- requence-0.8.1.dev63/PKG-INFO +0 -906
- requence-0.8.1.dev63/README.md +0 -894
- requence-0.8.1.dev63/requence/callbacks/context.py +0 -25
- requence-0.8.1.dev63/requence/callbacks/handler.py +0 -56
- requence-0.8.1.dev63/requence/requence_callback.py +0 -22
- requence-0.8.1.dev63/requence.egg-info/PKG-INFO +0 -906
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/MANIFEST.in +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/callbacks/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/client_properties.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/exceptions.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/errors.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/claim_check_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/context.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/file_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/stream_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/pending_uploads.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/requence_file.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/requence_stream.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/sanitize_log_data.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/stream_framing.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/transport.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/logger.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/obfuscase.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/py.typed +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/reachable.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/requence_file.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/requence_stream.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/cli.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/transformer.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/types.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/ui.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/ui_watch.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/abort_task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/ack_task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/cli.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/get_task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/ingress.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/protect_task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/task_watcher.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/types.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/updates.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/utils.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/context.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/errors.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/guards.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/message_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/transform.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/value_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/walk.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/utils.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/wire_codec.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/dependency_links.txt +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/entry_points.txt +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/requires.txt +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/top_level.txt +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/setup.cfg +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/tests/test_client_properties.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/tests/test_logger.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev67}/tests/test_wire_codec.py +0 -0
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: requence
|
|
3
|
+
Version: 0.8.1.dev67
|
|
4
|
+
Summary: Requence Service
|
|
5
|
+
Author: Torsten Blindert
|
|
6
|
+
Requires-Python: >=3.12
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
Requires-Dist: pika>=1.3.2
|
|
9
|
+
Requires-Dist: requests>=2.32.2
|
|
10
|
+
Requires-Dist: sseclient-py>=1.8.0
|
|
11
|
+
Requires-Dist: msgpack>=1.0.5
|
|
12
|
+
|
|
13
|
+
# requence
|
|
14
|
+
|
|
15
|
+
The official Python SDK for the Requence platform. It covers both halves of the integration:
|
|
16
|
+
|
|
17
|
+
- **`requence.service`** — connect a Python service to Requence and process messages
|
|
18
|
+
- **`requence.task`** — start and monitor Requence tasks programmatically
|
|
19
|
+
|
|
20
|
+
> **This README is a getting-started guide.** The reference for both halves lives at
|
|
21
|
+
> **<https://docs.requence.cloud>** — every page has a **Python** tab, including the places
|
|
22
|
+
> where Python's answer differs from TypeScript's.
|
|
23
|
+
|
|
24
|
+
## Requirements
|
|
25
|
+
|
|
26
|
+
Python 3.12 or later.
|
|
27
|
+
|
|
28
|
+
## Installation
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install requence
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Authentication
|
|
35
|
+
|
|
36
|
+
Copy a service's access token from the **Services** list view in the Requence UI
|
|
37
|
+
(**Copy credentials**). A task needs a personal or scoped access token instead.
|
|
38
|
+
|
|
39
|
+
Tokens are resolved in this order:
|
|
40
|
+
|
|
41
|
+
1. `access_token` passed to `Service()` / `Task()`
|
|
42
|
+
2. `REQUENCE_SERVICE_ACCESS_TOKEN` / `REQUENCE_TASK_ACCESS_TOKEN`, then `REQUENCE_ACCESS_TOKEN`
|
|
43
|
+
3. `requence.service_access_token` / `requence.task_access_token`, then `requence.access_token`
|
|
44
|
+
in `pyproject.toml`
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
REQUENCE_SERVICE_ACCESS_TOKEN=your-token python main.py
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Your first service
|
|
51
|
+
|
|
52
|
+
Create the service in the Requence UI first — its input schema, configuration schema and
|
|
53
|
+
outputs. Then implement the version:
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
from requence.service import Service
|
|
57
|
+
|
|
58
|
+
def handler(ctx):
|
|
59
|
+
return {"message": f"Hello, {ctx.input['name']}!"}
|
|
60
|
+
|
|
61
|
+
Service("1.0.0", handler)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
> **`Service(...)` never returns.** It consumes on the calling thread, so there is no instance
|
|
65
|
+
> to call `act()` or `close()` on. Use `Service.start(...)` when you need either — it returns
|
|
66
|
+
> the instance once connected, on a daemon consume thread. See
|
|
67
|
+
> [Starting & Stopping][lifecycle].
|
|
68
|
+
|
|
69
|
+
Generate type stubs for `ctx.input`, `ctx.configuration` and `ctx.to_output()` from the schemas
|
|
70
|
+
you defined in the UI:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
requence-service generate-types
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Your first task
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
from requence.task import Task
|
|
80
|
+
|
|
81
|
+
task = Task(task_template="my-template", input={"name": "World"})
|
|
82
|
+
result = task.sync.result # blocks until the task completes
|
|
83
|
+
|
|
84
|
+
print(result["result"])
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`task.sync` holds the blocking accessors; `await task.result` and `async for update in
|
|
88
|
+
task.updates` are the async equivalents.
|
|
89
|
+
|
|
90
|
+
## Where to read next
|
|
91
|
+
|
|
92
|
+
### Writing a service
|
|
93
|
+
|
|
94
|
+
| Topic | Page |
|
|
95
|
+
| ----------------------------------------------------------------------- | ------------------------------------------------- |
|
|
96
|
+
| The full walkthrough | [Getting Started][started] |
|
|
97
|
+
| `ctx.input`, `ctx.debug`, `retry`, `abort`, `skip`, `to_output`, `defer` | [Context API][context] |
|
|
98
|
+
| `prefetch`, `ssl_context`, TLS via environment | [Service Options][options] |
|
|
99
|
+
| `Service(...)` vs `Service.start(...)`, `close()` | [Starting & Stopping][lifecycle] |
|
|
100
|
+
| Generator handlers and `ctx.terminated` | [Continuous Mode][continuous] |
|
|
101
|
+
| `ctx.store` — what a node remembers past this message | [The Store][store] · [`ctx.store`][context-store] |
|
|
102
|
+
| `create_durable_callback`, `.for_(…)` | [Callbacks][callbacks] |
|
|
103
|
+
| `create_ui`, `ctx.render`, handler props | [Surfaces][surfaces] |
|
|
104
|
+
| `ctx.defer()` → `service.act()` | [Deferred Delivery][deferred] |
|
|
105
|
+
| Running locally against real tasks | [Dev Overlay][overlay] |
|
|
106
|
+
| `requence-service generate-types` | [Typing / CLI][typing] |
|
|
107
|
+
|
|
108
|
+
### Starting tasks
|
|
109
|
+
|
|
110
|
+
| Topic | Page |
|
|
111
|
+
| --------------------------------------------------------- | ------------------------------- |
|
|
112
|
+
| Options, `task.sync`, abort, protect, `require_ack` | [Starting Tasks][starting] |
|
|
113
|
+
| Sync and async iteration, the update types | [Streaming Updates][streaming] |
|
|
114
|
+
| `TaskWatcher` across every task | [Watching Tasks][watching] |
|
|
115
|
+
| `get_task` | [Fetching & Recreating][fetch] |
|
|
116
|
+
| `requence-task generate-types` | [CLI][cli] |
|
|
117
|
+
|
|
118
|
+
`test/demo-service/surface_demo.py` and `test/demo-python/` in the Requence repository are
|
|
119
|
+
runnable examples.
|
|
120
|
+
|
|
121
|
+
[started]: https://docs.requence.cloud/implementation/getting-started/
|
|
122
|
+
[context]: https://docs.requence.cloud/implementation/context-api/
|
|
123
|
+
[context-store]: https://docs.requence.cloud/implementation/context-api/#ctxstoreprivatekey-binding--ctxstoresharedkey-binding
|
|
124
|
+
[options]: https://docs.requence.cloud/implementation/advanced/service-options/
|
|
125
|
+
[lifecycle]: https://docs.requence.cloud/implementation/advanced/
|
|
126
|
+
[continuous]: https://docs.requence.cloud/planning/continuous-mode/
|
|
127
|
+
[store]: https://docs.requence.cloud/planning/store/
|
|
128
|
+
[callbacks]: https://docs.requence.cloud/implementation/callbacks/
|
|
129
|
+
[surfaces]: https://docs.requence.cloud/implementation/surfaces/
|
|
130
|
+
[deferred]: https://docs.requence.cloud/implementation/advanced/deferred-delivery/
|
|
131
|
+
[overlay]: https://docs.requence.cloud/implementation/advanced/dev-overlay/
|
|
132
|
+
[typing]: https://docs.requence.cloud/implementation/typing-cli/
|
|
133
|
+
[starting]: https://docs.requence.cloud/execution/starting-tasks/
|
|
134
|
+
[streaming]: https://docs.requence.cloud/execution/streaming/
|
|
135
|
+
[watching]: https://docs.requence.cloud/execution/watching-tasks/
|
|
136
|
+
[fetch]: https://docs.requence.cloud/execution/managing-tasks/
|
|
137
|
+
[cli]: https://docs.requence.cloud/execution/cli/
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# requence
|
|
2
|
+
|
|
3
|
+
The official Python SDK for the Requence platform. It covers both halves of the integration:
|
|
4
|
+
|
|
5
|
+
- **`requence.service`** — connect a Python service to Requence and process messages
|
|
6
|
+
- **`requence.task`** — start and monitor Requence tasks programmatically
|
|
7
|
+
|
|
8
|
+
> **This README is a getting-started guide.** The reference for both halves lives at
|
|
9
|
+
> **<https://docs.requence.cloud>** — every page has a **Python** tab, including the places
|
|
10
|
+
> where Python's answer differs from TypeScript's.
|
|
11
|
+
|
|
12
|
+
## Requirements
|
|
13
|
+
|
|
14
|
+
Python 3.12 or later.
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
pip install requence
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Authentication
|
|
23
|
+
|
|
24
|
+
Copy a service's access token from the **Services** list view in the Requence UI
|
|
25
|
+
(**Copy credentials**). A task needs a personal or scoped access token instead.
|
|
26
|
+
|
|
27
|
+
Tokens are resolved in this order:
|
|
28
|
+
|
|
29
|
+
1. `access_token` passed to `Service()` / `Task()`
|
|
30
|
+
2. `REQUENCE_SERVICE_ACCESS_TOKEN` / `REQUENCE_TASK_ACCESS_TOKEN`, then `REQUENCE_ACCESS_TOKEN`
|
|
31
|
+
3. `requence.service_access_token` / `requence.task_access_token`, then `requence.access_token`
|
|
32
|
+
in `pyproject.toml`
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
REQUENCE_SERVICE_ACCESS_TOKEN=your-token python main.py
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Your first service
|
|
39
|
+
|
|
40
|
+
Create the service in the Requence UI first — its input schema, configuration schema and
|
|
41
|
+
outputs. Then implement the version:
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
from requence.service import Service
|
|
45
|
+
|
|
46
|
+
def handler(ctx):
|
|
47
|
+
return {"message": f"Hello, {ctx.input['name']}!"}
|
|
48
|
+
|
|
49
|
+
Service("1.0.0", handler)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
> **`Service(...)` never returns.** It consumes on the calling thread, so there is no instance
|
|
53
|
+
> to call `act()` or `close()` on. Use `Service.start(...)` when you need either — it returns
|
|
54
|
+
> the instance once connected, on a daemon consume thread. See
|
|
55
|
+
> [Starting & Stopping][lifecycle].
|
|
56
|
+
|
|
57
|
+
Generate type stubs for `ctx.input`, `ctx.configuration` and `ctx.to_output()` from the schemas
|
|
58
|
+
you defined in the UI:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
requence-service generate-types
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Your first task
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from requence.task import Task
|
|
68
|
+
|
|
69
|
+
task = Task(task_template="my-template", input={"name": "World"})
|
|
70
|
+
result = task.sync.result # blocks until the task completes
|
|
71
|
+
|
|
72
|
+
print(result["result"])
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`task.sync` holds the blocking accessors; `await task.result` and `async for update in
|
|
76
|
+
task.updates` are the async equivalents.
|
|
77
|
+
|
|
78
|
+
## Where to read next
|
|
79
|
+
|
|
80
|
+
### Writing a service
|
|
81
|
+
|
|
82
|
+
| Topic | Page |
|
|
83
|
+
| ----------------------------------------------------------------------- | ------------------------------------------------- |
|
|
84
|
+
| The full walkthrough | [Getting Started][started] |
|
|
85
|
+
| `ctx.input`, `ctx.debug`, `retry`, `abort`, `skip`, `to_output`, `defer` | [Context API][context] |
|
|
86
|
+
| `prefetch`, `ssl_context`, TLS via environment | [Service Options][options] |
|
|
87
|
+
| `Service(...)` vs `Service.start(...)`, `close()` | [Starting & Stopping][lifecycle] |
|
|
88
|
+
| Generator handlers and `ctx.terminated` | [Continuous Mode][continuous] |
|
|
89
|
+
| `ctx.store` — what a node remembers past this message | [The Store][store] · [`ctx.store`][context-store] |
|
|
90
|
+
| `create_durable_callback`, `.for_(…)` | [Callbacks][callbacks] |
|
|
91
|
+
| `create_ui`, `ctx.render`, handler props | [Surfaces][surfaces] |
|
|
92
|
+
| `ctx.defer()` → `service.act()` | [Deferred Delivery][deferred] |
|
|
93
|
+
| Running locally against real tasks | [Dev Overlay][overlay] |
|
|
94
|
+
| `requence-service generate-types` | [Typing / CLI][typing] |
|
|
95
|
+
|
|
96
|
+
### Starting tasks
|
|
97
|
+
|
|
98
|
+
| Topic | Page |
|
|
99
|
+
| --------------------------------------------------------- | ------------------------------- |
|
|
100
|
+
| Options, `task.sync`, abort, protect, `require_ack` | [Starting Tasks][starting] |
|
|
101
|
+
| Sync and async iteration, the update types | [Streaming Updates][streaming] |
|
|
102
|
+
| `TaskWatcher` across every task | [Watching Tasks][watching] |
|
|
103
|
+
| `get_task` | [Fetching & Recreating][fetch] |
|
|
104
|
+
| `requence-task generate-types` | [CLI][cli] |
|
|
105
|
+
|
|
106
|
+
`test/demo-service/surface_demo.py` and `test/demo-python/` in the Requence repository are
|
|
107
|
+
runnable examples.
|
|
108
|
+
|
|
109
|
+
[started]: https://docs.requence.cloud/implementation/getting-started/
|
|
110
|
+
[context]: https://docs.requence.cloud/implementation/context-api/
|
|
111
|
+
[context-store]: https://docs.requence.cloud/implementation/context-api/#ctxstoreprivatekey-binding--ctxstoresharedkey-binding
|
|
112
|
+
[options]: https://docs.requence.cloud/implementation/advanced/service-options/
|
|
113
|
+
[lifecycle]: https://docs.requence.cloud/implementation/advanced/
|
|
114
|
+
[continuous]: https://docs.requence.cloud/planning/continuous-mode/
|
|
115
|
+
[store]: https://docs.requence.cloud/planning/store/
|
|
116
|
+
[callbacks]: https://docs.requence.cloud/implementation/callbacks/
|
|
117
|
+
[surfaces]: https://docs.requence.cloud/implementation/surfaces/
|
|
118
|
+
[deferred]: https://docs.requence.cloud/implementation/advanced/deferred-delivery/
|
|
119
|
+
[overlay]: https://docs.requence.cloud/implementation/advanced/dev-overlay/
|
|
120
|
+
[typing]: https://docs.requence.cloud/implementation/typing-cli/
|
|
121
|
+
[starting]: https://docs.requence.cloud/execution/starting-tasks/
|
|
122
|
+
[streaming]: https://docs.requence.cloud/execution/streaming/
|
|
123
|
+
[watching]: https://docs.requence.cloud/execution/watching-tasks/
|
|
124
|
+
[fetch]: https://docs.requence.cloud/execution/managing-tasks/
|
|
125
|
+
[cli]: https://docs.requence.cloud/execution/cli/
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "requence"
|
|
7
|
-
version = "0.8.1.
|
|
7
|
+
version = "0.8.1.dev67"
|
|
8
8
|
description = "Requence Service"
|
|
9
9
|
readme = { file = "README.md", content-type = "text/markdown" }
|
|
10
10
|
authors = [{ name = "Torsten Blindert" }]
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""Capability contexts of the callback handler (mirrors packages/callbacks/src/context.ts).
|
|
2
|
+
|
|
3
|
+
Documentation + optional static typing — see ``requence/files/handlers/context.py``
|
|
4
|
+
for how ctx capabilities work on the Python side.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from typing import Any, Callable, Protocol, TypedDict
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class CallbackRegistration(TypedDict):
|
|
11
|
+
callbackId: str
|
|
12
|
+
sourceId: str
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class CallbackEgressContext(Protocol):
|
|
16
|
+
# Registrar for this emission; absent ⇒ callables fail loud.
|
|
17
|
+
#
|
|
18
|
+
# The position comes along because a registry that grows is only actionable
|
|
19
|
+
# with it (#151): "you hold 50 000 callbacks" does not say which `yield`, and
|
|
20
|
+
# the handler already holds the path — it writes it into ``propertyPath`` on
|
|
21
|
+
# the very next line. A registrar that does not care may ignore it; nothing
|
|
22
|
+
# about the reference it returns depends on it.
|
|
23
|
+
on_callback: Callable[[Callable[[Any], None], list[str | int]], CallbackRegistration] | None
|
|
24
|
+
# The emission the value belongs to (embedded in callback references).
|
|
25
|
+
output_name: str | None
|
|
26
|
+
# The node this boundary emits for, as the operator dispatched it. Stamped
|
|
27
|
+
# into a **durable** reference, which is addressed by the emitting node rather
|
|
28
|
+
# than by a connection (#150) — so a boundary that cannot say which node it is
|
|
29
|
+
# cannot mint one, and the handler raises instead of emitting a reference
|
|
30
|
+
# nothing could route.
|
|
31
|
+
#
|
|
32
|
+
# Constant for every send of one message, unlike ``output_name``, so egress
|
|
33
|
+
# owners set it once when the boundary is built.
|
|
34
|
+
node_id: str | None
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class CallbackIngressContext(Protocol):
|
|
38
|
+
# Invocation dispatch for reconstructed callbacks; payload is the
|
|
39
|
+
# CallbackObject plus {"arg": ...}. Absent ⇒ invoking is a no-op.
|
|
40
|
+
on_callback_invoke: Callable[[dict], None] | None
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"""Bidirectional handler owning the ``RequenceCallback`` reference tag
|
|
2
|
+
(mirrors packages/callbacks/src/handler.ts).
|
|
3
|
+
|
|
4
|
+
Egress serializes any callable into a full callback reference: identity
|
|
5
|
+
(``callbackId``/``sourceId``) comes from ``ctx.on_callback``, the emission
|
|
6
|
+
from ``ctx.output_name``, and the position from the walk's ``path`` — the
|
|
7
|
+
reference's public identity (the operator validates invocation args against
|
|
8
|
+
the output schema at ``propertyPath``). A boundary that cannot register
|
|
9
|
+
callbacks (no ``ctx.on_callback``) fails loud.
|
|
10
|
+
|
|
11
|
+
A callable reaching this handler is a closure in the running process, so the
|
|
12
|
+
reference it mints is ``lifetime: 'connection'`` — the discriminator is stated
|
|
13
|
+
rather than implied, because a reference that omits it does not parse
|
|
14
|
+
(``wire.py``).
|
|
15
|
+
|
|
16
|
+
The one exception is a value the author minted with ``.for_(bound)``, which is a
|
|
17
|
+
callable only so that the walk offers it here at all (#147): it is already a
|
|
18
|
+
*reference* to a declaration and registers nothing, so it takes the durable arm
|
|
19
|
+
and this boundary's registry never grows by it. That is the whole point — a
|
|
20
|
+
three-week receiver's registry stays the size of its source rather than the size
|
|
21
|
+
of its traffic. Both arms are completed the same way, with the position the walk
|
|
22
|
+
knows and the emission the ctx knows.
|
|
23
|
+
|
|
24
|
+
Ingress reconstructs the reference into a callable that dispatches through
|
|
25
|
+
``ctx.on_callback_invoke`` — with no ``on_callback_invoke`` provided, invoking
|
|
26
|
+
the callback is a no-op; callers that forbid callbacks pass a raising
|
|
27
|
+
implementation.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
from typing import Any
|
|
31
|
+
|
|
32
|
+
from ..requence_callback import read_durable_callback_binding
|
|
33
|
+
from ..transformer import TransformContext, TransformPath, ValueHandler
|
|
34
|
+
from ..wire import REFERENCE_TAG_KEY, is_callback_object
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _serialize(callback: Any, ctx: TransformContext, path: TransformPath) -> dict:
|
|
38
|
+
binding = read_durable_callback_binding(callback)
|
|
39
|
+
if binding is not None:
|
|
40
|
+
# No ``ctx.on_callback`` check: a boundary that cannot register callbacks
|
|
41
|
+
# is refusing to hold a closure for the life of a message, and a durable
|
|
42
|
+
# reference asks nobody to hold anything. It addresses the service VERSION,
|
|
43
|
+
# which outlives every boundary here.
|
|
44
|
+
#
|
|
45
|
+
# ``ctx.node_id`` IS checked, because it is the whole address on the way
|
|
46
|
+
# back: the operator routes a durable invocation to the emitting node's
|
|
47
|
+
# version and hands the handler that node's configuration (#150). A
|
|
48
|
+
# reference minted without it would parse nowhere and be silently
|
|
49
|
+
# un-invokable, which is the failure this feature exists to remove — so it
|
|
50
|
+
# is named here, in the process that emitted it.
|
|
51
|
+
node_id = getattr(ctx, "node_id", None)
|
|
52
|
+
if not node_id:
|
|
53
|
+
raise Exception(
|
|
54
|
+
f'durable callback "{binding.name}" cannot be emitted on this '
|
|
55
|
+
f'boundary (no ctx.node_id) at path "{".".join(map(str, path))}"'
|
|
56
|
+
)
|
|
57
|
+
return {
|
|
58
|
+
REFERENCE_TAG_KEY: "RequenceCallback",
|
|
59
|
+
"lifetime": "durable",
|
|
60
|
+
"name": binding.name,
|
|
61
|
+
"nodeId": node_id,
|
|
62
|
+
"bound": binding.bound,
|
|
63
|
+
"outputName": getattr(ctx, "output_name", None),
|
|
64
|
+
"propertyPath": list(path),
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
on_callback = getattr(ctx, "on_callback", None)
|
|
68
|
+
if on_callback is None:
|
|
69
|
+
# handler raises are not path-wrapped by the transformer — carry the
|
|
70
|
+
# position in the message ourselves
|
|
71
|
+
raise Exception(
|
|
72
|
+
"functions are not serializable on this boundary (no ctx.on_callback) "
|
|
73
|
+
f'at path "{".".join(map(str, path))}"'
|
|
74
|
+
)
|
|
75
|
+
return {
|
|
76
|
+
# The path goes with the callable: the registrar counts per position, so a
|
|
77
|
+
# registry that grows can name the `yield` doing it (#151).
|
|
78
|
+
**on_callback(callback, list(path)),
|
|
79
|
+
"lifetime": "connection",
|
|
80
|
+
"outputName": getattr(ctx, "output_name", None),
|
|
81
|
+
"propertyPath": list(path),
|
|
82
|
+
REFERENCE_TAG_KEY: "RequenceCallback",
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _deserialize(ref: dict, ctx: TransformContext, _path: TransformPath):
|
|
87
|
+
def invoke(arg: Any) -> None:
|
|
88
|
+
on_callback_invoke = getattr(ctx, "on_callback_invoke", None)
|
|
89
|
+
if on_callback_invoke is not None:
|
|
90
|
+
on_callback_invoke({**ref, "arg": arg})
|
|
91
|
+
|
|
92
|
+
return invoke
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def create_requence_callback_handler() -> ValueHandler:
|
|
96
|
+
return ValueHandler(
|
|
97
|
+
tag="RequenceCallback",
|
|
98
|
+
can_handle=callable,
|
|
99
|
+
serialize=_serialize,
|
|
100
|
+
is_reference=is_callback_object,
|
|
101
|
+
deserialize=_deserialize,
|
|
102
|
+
)
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
from typing import TYPE_CHECKING, Any, Optional, Callable, cast
|
|
2
2
|
from .exceptions import RetryException, AbortException, SkipException
|
|
3
|
+
from .store import Store
|
|
3
4
|
from .utils import OutputValue
|
|
4
5
|
from .wire import DEFAULT_SURFACE_ID
|
|
5
6
|
import threading
|
|
@@ -41,7 +42,8 @@ class Context[I, C]:
|
|
|
41
42
|
on_log: Callable[[str, Any], None],
|
|
42
43
|
on_defer: Callable[[Optional[str]], str],
|
|
43
44
|
terminated: threading.Event,
|
|
44
|
-
on_render: Optional[Callable[["RequenceUI[Any]", Any, str], None]] = None
|
|
45
|
+
on_render: Optional[Callable[["RequenceUI[Any]", Any, str], None]] = None,
|
|
46
|
+
store: Optional[Store] = None
|
|
45
47
|
):
|
|
46
48
|
|
|
47
49
|
self.task_id = task_id
|
|
@@ -51,6 +53,16 @@ class Context[I, C]:
|
|
|
51
53
|
self.__on_defer = on_defer
|
|
52
54
|
self.__on_render = on_render
|
|
53
55
|
self.debug = Debug(on_log)
|
|
56
|
+
# What this node remembers past the end of this message, and past the
|
|
57
|
+
# end of this task (#211). Always present, so `context.store` is never
|
|
58
|
+
# the thing that is missing — a dispatch carrying no capability says so
|
|
59
|
+
# when a slot is read or written, not here.
|
|
60
|
+
#
|
|
61
|
+
# `store=None` only reaches a context built outside a dispatch (tests);
|
|
62
|
+
# such a store has nothing to address and says exactly that.
|
|
63
|
+
self.store = store if store is not None else Store(
|
|
64
|
+
url=None, signature=None, task_id=task_id, node_id=None
|
|
65
|
+
)
|
|
54
66
|
|
|
55
67
|
def retry(self, delay: Optional[int] = None):
|
|
56
68
|
raise RetryException(delay)
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
from typing import Optional, TypedDict, Any, Callable, Union
|
|
1
|
+
from typing import NotRequired, Optional, TypedDict, Any, Callable, Union
|
|
2
2
|
from ssl import SSLContext
|
|
3
3
|
|
|
4
4
|
class ServiceConfig(TypedDict, total=False):
|
|
@@ -21,10 +21,26 @@ class TaskOptions(TypedDict, total=False):
|
|
|
21
21
|
# URLs: claim-check offload threshold and RequenceFile/RequenceStream cap.
|
|
22
22
|
maxPayloadSize: Optional[int]
|
|
23
23
|
maxFileSize: Optional[int]
|
|
24
|
+
# The store capability (#211), copied onto every dispatch by the operator,
|
|
25
|
+
# which reads neither field. The URL is TOLD rather than derived — unlike a
|
|
26
|
+
# file reference, a store call carries no URL of its own — and it is the
|
|
27
|
+
# PUBLIC one, because an off-overlay service is a supported deployment.
|
|
28
|
+
storeUrl: Optional[str]
|
|
29
|
+
storeSignature: Optional[str]
|
|
24
30
|
|
|
25
31
|
class Payload(TypedDict, total=True):
|
|
26
32
|
input: Any
|
|
27
33
|
configuration: Any
|
|
34
|
+
# Which node of the graph this dispatch is for — the address a durable
|
|
35
|
+
# callback reference carries out with it (#150). NotRequired because a
|
|
36
|
+
# dispatch minted before it existed carries none, and that message simply
|
|
37
|
+
# cannot emit one.
|
|
38
|
+
nodeId: NotRequired[str]
|
|
39
|
+
# Set only when this dispatch is a configuration-function evaluation (#224).
|
|
40
|
+
# `nodeId` is then the HOST node's, and a `private` store slot addresses that
|
|
41
|
+
# node's configuration box rather than the host service's own. Not spelled
|
|
42
|
+
# `configuration`: that key above is this envelope's configuration VALUE.
|
|
43
|
+
configurationEval: NotRequired[bool]
|
|
28
44
|
options: TaskOptions
|
|
29
45
|
|
|
30
46
|
class ActorApi(TypedDict):
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
from .exceptions import StopException
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from threading import Event
|
|
4
|
+
from typing import Any, Generic, TypeVar, Callable, Optional, Union
|
|
5
|
+
|
|
6
|
+
T = TypeVar('T')
|
|
7
|
+
class Callback(Generic[T]):
|
|
8
|
+
def __init__(self, callback: Optional[Callable[[T], None]] = None):
|
|
9
|
+
self.__event = Event()
|
|
10
|
+
self.__result: Optional[Union[T, StopException]] = None
|
|
11
|
+
self.__callback = callback
|
|
12
|
+
|
|
13
|
+
def __call__(self, arg: Union[T, StopException]):
|
|
14
|
+
self.__result = arg
|
|
15
|
+
self.__event.set()
|
|
16
|
+
if self.__callback and not isinstance(arg, StopException):
|
|
17
|
+
self.__callback(arg)
|
|
18
|
+
|
|
19
|
+
def response(self) -> T:
|
|
20
|
+
self.__event.wait()
|
|
21
|
+
if (isinstance(self.__result, StopException)):
|
|
22
|
+
raise self.__result
|
|
23
|
+
return self.__result # type: ignore
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass(frozen=True)
|
|
27
|
+
class DurableCallbackBinding:
|
|
28
|
+
"""What a ``.for_(bound)`` reference carries before the boundary completes it:
|
|
29
|
+
the declaration's name and the data bound to this emission. The position
|
|
30
|
+
(``outputName``/``propertyPath``) is added where it is known — the value walk —
|
|
31
|
+
exactly as it is for the connection arm."""
|
|
32
|
+
|
|
33
|
+
name: str
|
|
34
|
+
bound: Any
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
# Where a ``.for_(bound)`` reference keeps its binding.
|
|
38
|
+
#
|
|
39
|
+
# A dunder-ish attribute name rather than a private one, and read structurally
|
|
40
|
+
# below rather than by ``isinstance``: two copies of this package in one process (a
|
|
41
|
+
# service depending on an SDK that depends on it) must agree, which is the same
|
|
42
|
+
# reason the TS side uses ``Symbol.for`` rather than a fresh symbol. The name is
|
|
43
|
+
# long enough that an author's own callable cannot carry one by accident.
|
|
44
|
+
_DURABLE_CALLBACK_BINDING = "__requence_durable_callback_binding__"
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def create_durable_callback_reference(binding: DurableCallbackBinding) -> Callable[..., Any]:
|
|
48
|
+
"""Mints the value an author emits in place of a closure — what
|
|
49
|
+
``create_durable_callback(...).for_(bound)`` returns (#147).
|
|
50
|
+
|
|
51
|
+
It is a **callable** carrying the binding on an attribute, rather than the wire
|
|
52
|
+
object it will become, for the reason the TS side mints a function: the egress
|
|
53
|
+
walk only offers *complex* values to a handler, and a plain dict is traversable
|
|
54
|
+
structure — a literal reference would be walked straight through and emitted
|
|
55
|
+
without the ``outputName``/``propertyPath`` the operator validates against,
|
|
56
|
+
which no schema parse downstream would accept. A callable is what the callback
|
|
57
|
+
handler claims.
|
|
58
|
+
|
|
59
|
+
Calling it *here*, in the emitting service, is the author's mistake — a durable
|
|
60
|
+
callback runs where the invocation is delivered, never inline — so it says so
|
|
61
|
+
rather than doing nothing."""
|
|
62
|
+
|
|
63
|
+
def reference(*_args: Any, **_kwargs: Any) -> Any:
|
|
64
|
+
raise Exception(
|
|
65
|
+
f'durable callback "{binding.name}" was called in the service that '
|
|
66
|
+
"emitted it — a durable callback reference is a value to emit, and it "
|
|
67
|
+
"runs only when the graph invokes it"
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
# Named after the callback, not after this closure. It costs nothing and it is
|
|
71
|
+
# what a traceback and a debugger read.
|
|
72
|
+
reference.__name__ = binding.name
|
|
73
|
+
reference.__qualname__ = binding.name
|
|
74
|
+
setattr(reference, _DURABLE_CALLBACK_BINDING, binding)
|
|
75
|
+
return reference
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def read_durable_callback_binding(value: Any) -> Optional[DurableCallbackBinding]:
|
|
79
|
+
"""The binding a value carries, or ``None`` when it is an ordinary callable —
|
|
80
|
+
which is how the callback handler tells the two lifetimes apart on egress."""
|
|
81
|
+
if not callable(value):
|
|
82
|
+
return None
|
|
83
|
+
binding = getattr(value, _DURABLE_CALLBACK_BINDING, None)
|
|
84
|
+
return binding if isinstance(getattr(binding, "name", None), str) else None
|