taskwire 0.4.4__tar.gz → 0.5.1__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.
- {taskwire-0.4.4 → taskwire-0.5.1}/PKG-INFO +21 -38
- taskwire-0.5.1/README.md +73 -0
- taskwire-0.5.1/conformance/README.md +9 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/pyproject.toml +3 -4
- {taskwire-0.4.4 → taskwire-0.5.1}/pyproject.toml.orig +20 -31
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/__init__.py +7 -7
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/ambient.py +16 -22
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/calls.py +4 -6
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/conformance.py +31 -66
- taskwire-0.5.1/taskwire/contrib/__init__.py +14 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/contrib/asgi.py +17 -22
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/contrib/celery.py +29 -50
- taskwire-0.5.1/taskwire/contrib/fastapi.py +144 -0
- taskwire-0.5.1/taskwire/contrib/muxws.py +300 -0
- taskwire-0.5.1/taskwire/contrib/openapi.py +141 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/contrib/redis_store.py +35 -66
- taskwire-0.5.1/taskwire/contrib/schema.py +301 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/contrib/threads.py +6 -9
- taskwire-0.5.1/taskwire/contrib/viewsets.py +383 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/contrib/viewsets_events.py +9 -6
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/decorators.py +17 -23
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/delivery.py +26 -34
- taskwire-0.5.1/taskwire/headers.py +25 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/models.py +57 -39
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/publish.py +2 -3
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/reader.py +16 -33
- taskwire-0.5.1/taskwire/register.py +134 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/reporter.py +126 -297
- taskwire-0.5.1/taskwire/rest.py +345 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/settings.py +10 -21
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/store.py +72 -154
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/transport.py +16 -29
- taskwire-0.4.4/README.md +0 -90
- taskwire-0.4.4/conformance/README.md +0 -10
- taskwire-0.4.4/taskwire/contrib/__init__.py +0 -17
- taskwire-0.4.4/taskwire/contrib/fastapi.py +0 -82
- taskwire-0.4.4/taskwire/contrib/muxws.py +0 -361
- taskwire-0.4.4/taskwire/contrib/schema.py +0 -231
- taskwire-0.4.4/taskwire/contrib/viewsets.py +0 -529
- taskwire-0.4.4/taskwire/headers.py +0 -36
- taskwire-0.4.4/taskwire/register.py +0 -182
- taskwire-0.4.4/taskwire/rest.py +0 -365
- {taskwire-0.4.4 → taskwire-0.5.1}/LICENSE +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/exception-names.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/sequences/.gitkeep +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/aggregate-counts.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/aggregate-waiting-input-dominates.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/dialog-request-open.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/envelope-cancel.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/envelope-progress.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/envelope-snapshot.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/error-dispatch-failed.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-percent-absent.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-percent-null.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-private.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-shared-origins.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-state-cancelled.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-state-done.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-state-failed.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-state-queued.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-state-running.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/progress-state-waiting-input.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/register-empty-null-aggregate.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/register-v2-with-aggregate.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/result-kind-and-params.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/result-label-and-value-no-ref.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/result-ref-with-expires-at.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/snapshot-v2-wall-clock-rev.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/snapshot-waiting-input-uncollected-result.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/text-key-and-text.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/text-key-only.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/text-key-params-and-text.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/conformance/wire/text-text-only.json +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/contrib/wsgi.py +0 -0
- {taskwire-0.4.4 → taskwire-0.5.1}/taskwire/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: taskwire
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.1
|
|
4
4
|
Summary: Progress reporting and awaitable dialogs for long-running server-side operations.
|
|
5
5
|
Keywords: progress,dialogs,celery,fastapi,websocket,dynamicforms
|
|
6
6
|
Author: Jure Erznožnik
|
|
@@ -21,9 +21,9 @@ Requires-Dist: celery>=5.3 ; extra == 'celery'
|
|
|
21
21
|
Requires-Dist: nest-asyncio>=1.6 ; extra == 'celery'
|
|
22
22
|
Requires-Dist: fastapi>=0.100 ; extra == 'fastapi'
|
|
23
23
|
Requires-Dist: muxws>=0.4.1 ; extra == 'muxws'
|
|
24
|
-
Requires-Dist: dynamicforms-fastapi-viewsets[muxws]>=0.
|
|
24
|
+
Requires-Dist: dynamicforms-fastapi-viewsets[muxws]>=0.15.3 ; extra == 'muxws'
|
|
25
25
|
Requires-Dist: redis>=5.0 ; extra == 'redis'
|
|
26
|
-
Requires-Dist: dynamicforms-fastapi-viewsets>=0.
|
|
26
|
+
Requires-Dist: dynamicforms-fastapi-viewsets>=0.15.3 ; extra == 'viewsets'
|
|
27
27
|
Requires-Python: >=3.10
|
|
28
28
|
Project-URL: Homepage, https://github.com/velis74/taskwire
|
|
29
29
|
Project-URL: Repository, https://github.com/velis74/taskwire
|
|
@@ -42,56 +42,39 @@ Progress reporting and awaitable dialogs for long-running operations, in Python
|
|
|
42
42
|
|
|
43
43
|
A long-running job — an import, a report, a batch — needs to tell whoever started it what it is
|
|
44
44
|
doing while it is doing it, and sometimes needs to ask them something before it can continue.
|
|
45
|
-
taskwire
|
|
45
|
+
taskwire provides:
|
|
46
46
|
|
|
47
|
-
- **progress**, with nested subtasks whose percentages compose
|
|
48
|
-
each other, and commits coalesced
|
|
47
|
+
- **progress**, with nested subtasks whose percentages compose rather than overwrite
|
|
48
|
+
each other, and commits coalesced to one per interval;
|
|
49
49
|
- **awaitable dialogs** — the worker asks a question mid-job and blocks until the answer arrives,
|
|
50
|
-
with the first answer winning across every tab
|
|
50
|
+
with the first answer winning across every open tab;
|
|
51
51
|
- **cancellation**, cooperative and sticky, which raises in the worker at its next progress call;
|
|
52
|
-
- **collectable results** — the job parks a file or a value for later collection and
|
|
52
|
+
- **collectable results** — the job parks a file or a value for later collection and exits,
|
|
53
53
|
holding no worker while the record waits.
|
|
54
54
|
|
|
55
|
-
## The
|
|
55
|
+
## The store holds the state
|
|
56
56
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
current state, and asking for it is always enough.
|
|
57
|
+
Every state change is written to the store before anything is pushed, so a dropped, coalesced or
|
|
58
|
+
suppressed push never changes what the next read returns. There is no event log, no sequence
|
|
59
|
+
numbers and no replay: a client reads current state.
|
|
61
60
|
|
|
62
61
|
## One protocol, three implementations
|
|
63
62
|
|
|
64
|
-
The layering is the shape of the source tree:
|
|
65
|
-
|
|
66
|
-
```text
|
|
67
|
-
protocol documents, envelopes, the six kinds, the state
|
|
68
|
-
│ machines, validation. Knows of no transport.
|
|
69
|
-
┌───────────┼───────────┐
|
|
70
|
-
local REST WS three independent implementations of it
|
|
71
|
-
│ │ │
|
|
72
|
-
(none) fastapi / asgi muxws one adapter each, to the world outside
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
The **protocol** is specified once and depends on nothing. Each **implementation** carries it over
|
|
76
|
-
one medium and is written against the protocol layer alone, never against another implementation.
|
|
77
|
-
Each **adapter** is the thin piece that binds an implementation to a particular framework, and is
|
|
78
|
-
the only place that framework is imported.
|
|
79
|
-
|
|
80
63
|
| Implementation | Carries the protocol over | Adapter | Needs |
|
|
81
64
|
|---|---|---|---|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
|
|
|
65
|
+
| local | the process itself, no serialisation | none | nothing |
|
|
66
|
+
| REST | request/response polling | `contrib.viewsets`, `contrib.fastapi`, `contrib.asgi` | nothing in core |
|
|
67
|
+
| WS | one push per envelope down, the six calls up | `contrib.muxws` | [muxws](https://docs.velis.si/muxws/) |
|
|
85
68
|
|
|
86
|
-
Swapping one for another changes latency
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
69
|
+
Swapping one for another changes latency only. Both languages ship the protocol and the operating
|
|
70
|
+
half, so a browser-only application runs operations as well as watching them; the adapters, the
|
|
71
|
+
Redis store and the Celery entry are Python's, and the polling client and the register are
|
|
72
|
+
TypeScript's. See [Transports](https://docs.velis.si/taskwire/guide/transports.html).
|
|
90
73
|
|
|
91
74
|
## Install
|
|
92
75
|
|
|
93
76
|
```bash
|
|
94
|
-
pip install taskwire # core: no runtime dependencies
|
|
77
|
+
pip install taskwire # core: no runtime dependencies
|
|
95
78
|
pip install "taskwire[redis]" # cross-process store and backplane
|
|
96
79
|
pip install "taskwire[fastapi]" # the REST adapter
|
|
97
80
|
pip install "taskwire[viewsets]" # the REST API as a fastapi-viewsets viewset
|
|
@@ -115,7 +98,7 @@ progress, awaitable dialogs, cancellation and collectable results. See [`demo/RE
|
|
|
115
98
|
|
|
116
99
|
## Status
|
|
117
100
|
|
|
118
|
-
Pre-1.0
|
|
101
|
+
Pre-1.0. The wire format is versioned independently of the package
|
|
119
102
|
(`Envelope.v`), so package semver says nothing about it.
|
|
120
103
|
|
|
121
104
|
## Links
|
taskwire-0.5.1/README.md
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# <img src="taskwire-icon.svg" alt="" width="40" height="40" style="vertical-align: middle"> taskwire
|
|
2
|
+
|
|
3
|
+
Progress reporting and awaitable dialogs for long-running operations, in Python and TypeScript.
|
|
4
|
+
|
|
5
|
+
A long-running job — an import, a report, a batch — needs to tell whoever started it what it is
|
|
6
|
+
doing while it is doing it, and sometimes needs to ask them something before it can continue.
|
|
7
|
+
taskwire provides:
|
|
8
|
+
|
|
9
|
+
- **progress**, with nested subtasks whose percentages compose rather than overwrite
|
|
10
|
+
each other, and commits coalesced to one per interval;
|
|
11
|
+
- **awaitable dialogs** — the worker asks a question mid-job and blocks until the answer arrives,
|
|
12
|
+
with the first answer winning across every open tab;
|
|
13
|
+
- **cancellation**, cooperative and sticky, which raises in the worker at its next progress call;
|
|
14
|
+
- **collectable results** — the job parks a file or a value for later collection and exits,
|
|
15
|
+
holding no worker while the record waits.
|
|
16
|
+
|
|
17
|
+
## The store holds the state
|
|
18
|
+
|
|
19
|
+
Every state change is written to the store before anything is pushed, so a dropped, coalesced or
|
|
20
|
+
suppressed push never changes what the next read returns. There is no event log, no sequence
|
|
21
|
+
numbers and no replay: a client reads current state.
|
|
22
|
+
|
|
23
|
+
## One protocol, three implementations
|
|
24
|
+
|
|
25
|
+
| Implementation | Carries the protocol over | Adapter | Needs |
|
|
26
|
+
|---|---|---|---|
|
|
27
|
+
| local | the process itself, no serialisation | none | nothing |
|
|
28
|
+
| REST | request/response polling | `contrib.viewsets`, `contrib.fastapi`, `contrib.asgi` | nothing in core |
|
|
29
|
+
| WS | one push per envelope down, the six calls up | `contrib.muxws` | [muxws](https://docs.velis.si/muxws/) |
|
|
30
|
+
|
|
31
|
+
Swapping one for another changes latency only. Both languages ship the protocol and the operating
|
|
32
|
+
half, so a browser-only application runs operations as well as watching them; the adapters, the
|
|
33
|
+
Redis store and the Celery entry are Python's, and the polling client and the register are
|
|
34
|
+
TypeScript's. See [Transports](https://docs.velis.si/taskwire/guide/transports.html).
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install taskwire # core: no runtime dependencies
|
|
40
|
+
pip install "taskwire[redis]" # cross-process store and backplane
|
|
41
|
+
pip install "taskwire[fastapi]" # the REST adapter
|
|
42
|
+
pip install "taskwire[viewsets]" # the REST API as a fastapi-viewsets viewset
|
|
43
|
+
pip install "taskwire[celery]" # the worker entry point
|
|
44
|
+
pip install "taskwire[muxws]" # the WebSocket transport
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm install taskwire
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## The demo
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
uv sync && npm ci
|
|
55
|
+
uv run python demo.py # then open http://127.0.0.1:5174
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
A night batch over one book: four back-office jobs that between them exercise progress, nested
|
|
59
|
+
progress, awaitable dialogs, cancellation and collectable results. See [`demo/README.md`](demo/README.md).
|
|
60
|
+
|
|
61
|
+
## Status
|
|
62
|
+
|
|
63
|
+
Pre-1.0. The wire format is versioned independently of the package
|
|
64
|
+
(`Envelope.v`), so package semver says nothing about it.
|
|
65
|
+
|
|
66
|
+
## Links
|
|
67
|
+
|
|
68
|
+
- [Documentation](https://docs.velis.si/taskwire/)
|
|
69
|
+
- [Repository](https://github.com/velis74/taskwire)
|
|
70
|
+
|
|
71
|
+
## License
|
|
72
|
+
|
|
73
|
+
MIT. Copyright (c) 2026 Jure Erznožnik.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Conformance fixtures
|
|
2
|
+
|
|
3
|
+
Language-neutral JSON, read in place by both `pytest` and `vitest`, with no copy step (TW-PKG-002), so
|
|
4
|
+
both languages test against the same files.
|
|
5
|
+
|
|
6
|
+
| Path | Holds |
|
|
7
|
+
|---|---|
|
|
8
|
+
| `wire/` | One document per file, in the shapes of specification §3. |
|
|
9
|
+
| `exception-names.json` | Exception class names and the snake_case names derived from them (`exception_name` / `exceptionName`). |
|
|
@@ -4,7 +4,7 @@ build-backend = "uv_build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "taskwire"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.5.1"
|
|
8
8
|
description = "Progress reporting and awaitable dialogs for long-running server-side operations."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
@@ -43,10 +43,10 @@ celery = [
|
|
|
43
43
|
"nest_asyncio>=1.6",
|
|
44
44
|
]
|
|
45
45
|
fastapi = ["fastapi>=0.100"]
|
|
46
|
-
viewsets = ["dynamicforms-fastapi-viewsets>=0.
|
|
46
|
+
viewsets = ["dynamicforms-fastapi-viewsets>=0.15.3"]
|
|
47
47
|
muxws = [
|
|
48
48
|
"muxws>=0.4.1",
|
|
49
|
-
"dynamicforms-fastapi-viewsets[muxws]>=0.
|
|
49
|
+
"dynamicforms-fastapi-viewsets[muxws]>=0.15.3",
|
|
50
50
|
]
|
|
51
51
|
|
|
52
52
|
[project.urls]
|
|
@@ -89,7 +89,6 @@ asyncio_default_fixture_loop_scope = "function"
|
|
|
89
89
|
exclude = [
|
|
90
90
|
"docs",
|
|
91
91
|
"design",
|
|
92
|
-
"ts",
|
|
93
92
|
"node_modules",
|
|
94
93
|
"dist",
|
|
95
94
|
"build",
|
|
@@ -4,7 +4,7 @@ build-backend = "uv_build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "taskwire"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.5.1"
|
|
8
8
|
description = "Progress reporting and awaitable dialogs for long-running server-side operations."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
@@ -24,28 +24,24 @@ classifiers = [
|
|
|
24
24
|
"Topic :: Internet :: WWW/HTTP",
|
|
25
25
|
"Typing :: Typed",
|
|
26
26
|
]
|
|
27
|
-
dependencies = [] #
|
|
27
|
+
dependencies = [] # core has no runtime dependencies (TW-CORE-006)
|
|
28
28
|
|
|
29
29
|
[project.optional-dependencies]
|
|
30
30
|
redis = ["redis>=5.0"]
|
|
31
31
|
celery = ["celery>=5.3", "nest_asyncio>=1.6"]
|
|
32
32
|
fastapi = ["fastapi>=0.100"]
|
|
33
|
-
# >=0.
|
|
34
|
-
#
|
|
35
|
-
# verbatim
|
|
36
|
-
#
|
|
37
|
-
#
|
|
38
|
-
#
|
|
39
|
-
#
|
|
40
|
-
|
|
41
|
-
#
|
|
42
|
-
#
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
# extra needs the viewset layer's muxws half as well as muxws itself. >=0.4.1: `Peer.close()` sends
|
|
46
|
-
# every queued frame before closing the socket, so the `goaway` of `goaway_if_stale` (TW-WS-007)
|
|
47
|
-
# reaches the client.
|
|
48
|
-
muxws = ["muxws>=0.4.1", "dynamicforms-fastapi-viewsets[muxws]>=0.13.0"]
|
|
33
|
+
# >=0.15.3: `Middleware.openapi_parameters_for()`, through which `TaskwireMiddleware` declares its header
|
|
34
|
+
# on the operations it tracks only. It also provides: namespaced error codes, forwarded by
|
|
35
|
+
# `TaskwireMiddleware` verbatim; one error body for every viewset route; the execution hook and the
|
|
36
|
+
# Idempotency-Key helpers; a muxws command that runs its action to the end when its stream ends early
|
|
37
|
+
# (TW-CALL-*); delivery filters that run on poll as on push (TW-EVT-004); and executor outcomes as
|
|
38
|
+
# library exceptions plus `Middleware.executor_started()` / `on_transition()`, reported on a process
|
|
39
|
+
# exit in every pool, so `contrib/viewsets.py` imports no Celery (TW-CALL-101, TW-CALL-105).
|
|
40
|
+
viewsets = ["dynamicforms-fastapi-viewsets>=0.15.3"]
|
|
41
|
+
# The six request/response calls run as viewset commands over the socket (TW-REST-004).
|
|
42
|
+
# muxws >=0.4.1: `Peer.close()` flushes queued frames, so the `goaway` of `goaway_if_stale`
|
|
43
|
+
# (TW-WS-007) reaches the client.
|
|
44
|
+
muxws = ["muxws>=0.4.1", "dynamicforms-fastapi-viewsets[muxws]>=0.15.3"]
|
|
49
45
|
|
|
50
46
|
[dependency-groups]
|
|
51
47
|
# Everything the test suite, the linters and the demo need.
|
|
@@ -68,11 +64,8 @@ Repository = "https://github.com/velis74/taskwire"
|
|
|
68
64
|
Issues = "https://github.com/velis74/taskwire/issues"
|
|
69
65
|
Documentation = "https://docs.velis.si/taskwire/"
|
|
70
66
|
|
|
71
|
-
#
|
|
72
|
-
#
|
|
73
|
-
# at it, so it is named here. `packaging_test.py::test_python_and_npm_versions_match` and
|
|
74
|
-
# `vue/packaging.spec.ts` both compare against `package.json`, transitively pinning all three, but only
|
|
75
|
-
# once a release has actually bumped this file too.
|
|
67
|
+
# `vue/index.ts` exports the version as `VERSION`; the release tool bumps it with the two manifests.
|
|
68
|
+
# `packaging_test.py` and `vue/packaging.spec.ts` compare all three against `package.json`.
|
|
76
69
|
[tool.publish]
|
|
77
70
|
additional_files = ["vue/index.ts"]
|
|
78
71
|
|
|
@@ -87,19 +80,15 @@ asyncio_mode = "auto"
|
|
|
87
80
|
asyncio_default_fixture_loop_scope = "function"
|
|
88
81
|
|
|
89
82
|
[tool.ruff]
|
|
90
|
-
# `design`
|
|
91
|
-
|
|
92
|
-
exclude = ['docs', 'design', 'ts', 'node_modules', 'dist', 'build', '.git', '.idea',
|
|
83
|
+
# `design` and `docs` are Markdown with Python code blocks, which ruff would otherwise reformat.
|
|
84
|
+
exclude = ['docs', 'design', 'node_modules', 'dist', 'build', '.git', '.idea',
|
|
93
85
|
'.pytest_cache', '.ruff_cache', '.venv']
|
|
94
86
|
line-length = 120
|
|
95
87
|
|
|
96
88
|
[tool.ruff.lint]
|
|
97
89
|
select = ["E", "W", "F", "I", "Q", "B", "UP", "N", "PT", "S", "C4", "ARG"]
|
|
98
|
-
# S105
|
|
99
|
-
#
|
|
100
|
-
# explicitly "never an authorization grant" (specification §1, TW-SEC-003). The namespace is the
|
|
101
|
-
# only authorization scope, and the library handles no passwords, keys or credentials of any kind,
|
|
102
|
-
# so every hit of these three rules is a false positive on a core domain word.
|
|
90
|
+
# S105-S107: `token` is an operation's address, not a credential (TW-SEC-003); the library handles
|
|
91
|
+
# no passwords, keys or credentials.
|
|
103
92
|
ignore = ["E731", "E722", "C408", "S105", "S106", "S107"]
|
|
104
93
|
fixable = ["ALL"]
|
|
105
94
|
unfixable = []
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
"""taskwire - progress reporting and awaitable dialogs for long-running operations.
|
|
2
2
|
|
|
3
|
-
The store is the truth; a push
|
|
4
|
-
is sent
|
|
5
|
-
returns
|
|
3
|
+
The store is the source of truth; a push only lowers latency. Every state change is written before
|
|
4
|
+
anything is sent, so a dropped, coalesced or suppressed push never changes what the next read
|
|
5
|
+
returns, and the transport can be swapped without changing behaviour.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
(`
|
|
10
|
-
|
|
7
|
+
One protocol (the documents of §3 and the state machines of §4, in `models`) and three transports:
|
|
8
|
+
local (`transport.LocalTransport`), REST (`rest`, `contrib.viewsets`) and WebSocket
|
|
9
|
+
(`contrib.muxws`); REST and WebSocket share the calls of TW-REST-004. Nothing in the core imports a
|
|
10
|
+
framework, a driver or a UI library (TW-CORE-006).
|
|
11
11
|
"""
|
|
12
12
|
|
|
13
13
|
from __future__ import annotations
|
|
@@ -1,20 +1,17 @@
|
|
|
1
1
|
"""The ambient reporter: `taskwire.progress` and `taskwire.ask`.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
once at the top, and `await progress.set(...)` works anywhere underneath.
|
|
3
|
+
Binds a `Reporter` for the current context, so code below `operation()` reports through
|
|
4
|
+
`progress` without receiving a reporter argument.
|
|
6
5
|
|
|
7
|
-
|
|
8
|
-
TW-AMB-002 makes an unbound proxy a *silent* no-op - so a proxy that worked under Node and no-opped
|
|
9
|
-
in a browser would fail as a progress bar that never moves, with nothing logged anywhere.
|
|
6
|
+
Python only (TW-SYM-004): `contextvars` has no browser equivalent.
|
|
10
7
|
|
|
11
|
-
##
|
|
8
|
+
## Concurrent siblings
|
|
12
9
|
|
|
13
|
-
Concurrent siblings MUST each receive their own reporter
|
|
10
|
+
Concurrent siblings MUST each receive their own reporter explicitly (TW-NEST-014). The ambient
|
|
14
11
|
binding is one variable; a `gather` is many tasks sharing it.
|
|
15
12
|
|
|
16
13
|
```python
|
|
17
|
-
# WRONG - every branch writes through one binding,
|
|
14
|
+
# WRONG - every branch writes through one binding, onto one range
|
|
18
15
|
async def wrong(reporter):
|
|
19
16
|
with reporter.subtask(0, 50):
|
|
20
17
|
await asyncio.gather(load_a(), load_b(), load_c()) # all three use `progress`
|
|
@@ -25,8 +22,8 @@ async def right(reporter):
|
|
|
25
22
|
await asyncio.gather(load_a(a), load_b(b), load_c(c))
|
|
26
23
|
```
|
|
27
24
|
|
|
28
|
-
`contextvars` copies
|
|
29
|
-
|
|
25
|
+
`contextvars` copies the context per task: every task of the `gather` reports through the same
|
|
26
|
+
binding, onto one range.
|
|
30
27
|
"""
|
|
31
28
|
|
|
32
29
|
from __future__ import annotations
|
|
@@ -46,9 +43,8 @@ def bind(reporter: Any) -> contextvars.Token:
|
|
|
46
43
|
def unbind(token: contextvars.Token | None) -> None:
|
|
47
44
|
"""Reset via the `Token` (TW-AMB-005).
|
|
48
45
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
progress would land on operation B's key (TW-INV-011).
|
|
46
|
+
Writing `None` back instead would leave a raising task's binding to the next task on the same
|
|
47
|
+
pooled thread, and its progress would land on another operation's key (TW-INV-011).
|
|
52
48
|
"""
|
|
53
49
|
if token is not None:
|
|
54
50
|
_current.reset(token)
|
|
@@ -62,16 +58,15 @@ def current_reporter() -> Any:
|
|
|
62
58
|
class _AmbientProgress:
|
|
63
59
|
"""The module-level singleton exposing the identical `Reporter` surface (TW-AMB-001).
|
|
64
60
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
61
|
+
Each method mirrors the `Reporter` member of the same name. With nothing bound, every method is
|
|
62
|
+
a silent no-op (TW-AMB-002), so library code that reports progress runs outside an operation
|
|
63
|
+
without a warning.
|
|
68
64
|
"""
|
|
69
65
|
|
|
70
66
|
async def set(self, **kwargs: Any) -> None: # noqa: A003 - mirrors Reporter.set
|
|
71
67
|
reporter = _current.get()
|
|
72
68
|
if reporter is None:
|
|
73
|
-
#
|
|
74
|
-
# must not pass merely because it ran outside one (TW-PROG-012).
|
|
69
|
+
# `state` is rejected unbound too, as inside an operation (TW-PROG-012).
|
|
75
70
|
if "state" in kwargs:
|
|
76
71
|
raise ValueError("taskwire: Reporter.set() has no `state` keyword (TW-PROG-012)")
|
|
77
72
|
return None
|
|
@@ -80,8 +75,7 @@ class _AmbientProgress:
|
|
|
80
75
|
async def ask(self, dialog_id: str, **kwargs: Any) -> Any:
|
|
81
76
|
"""TW-AMB-003: `taskwire.ask` is this.
|
|
82
77
|
|
|
83
|
-
Unbound,
|
|
84
|
-
blocking forever - the one place where the no-op is visible in a return value.
|
|
78
|
+
Unbound, returns `None` without waiting.
|
|
85
79
|
"""
|
|
86
80
|
reporter = _current.get()
|
|
87
81
|
if reporter is None:
|
|
@@ -158,4 +152,4 @@ progress = _AmbientProgress()
|
|
|
158
152
|
"""The ambient reporter (TW-AMB-001). Bound by `operation()` and by `with reporter.subtask(a, b):`."""
|
|
159
153
|
|
|
160
154
|
ask = progress.ask
|
|
161
|
-
"""TW-AMB-003: `taskwire.ask` is `progress.ask
|
|
155
|
+
"""TW-AMB-003: `taskwire.ask` is `progress.ask`."""
|
|
@@ -14,10 +14,8 @@ each has one primitive:
|
|
|
14
14
|
A process that learns that an execution ended without writing its terminal state - an executor that
|
|
15
15
|
ended it from outside - ends the operation with `end_call()`.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
`taskwire.contrib.viewsets.TaskwireMiddleware`. Both context managers have an asynchronous and a
|
|
20
|
-
synchronous form, as `operation()` has (TW-API-002).
|
|
17
|
+
Both context managers have an asynchronous and a synchronous form, as `operation()` has
|
|
18
|
+
(TW-API-002).
|
|
21
19
|
|
|
22
20
|
```python
|
|
23
21
|
async with receive_call(call, dispatch_errors=(BrokerDown,)):
|
|
@@ -162,7 +160,7 @@ class Call:
|
|
|
162
160
|
|
|
163
161
|
def carried(self) -> dict[str, str]:
|
|
164
162
|
"""The values that cross a process boundary: `token` and `session`, as plain strings
|
|
165
|
-
(TW-CELERY-003).
|
|
163
|
+
(TW-CELERY-003)."""
|
|
166
164
|
return {"token": self.token, "session": self.session}
|
|
167
165
|
|
|
168
166
|
@classmethod
|
|
@@ -424,7 +422,7 @@ async def end_call(
|
|
|
424
422
|
asking_error: Error | None = None,
|
|
425
423
|
) -> bool:
|
|
426
424
|
"""End the operation of a call whose execution ended without writing its terminal state
|
|
427
|
-
(TW-CALL-008).
|
|
425
|
+
(TW-CALL-008).
|
|
428
426
|
|
|
429
427
|
Writes `failed` with `error`, withdrawing the open dialogs in the same step, when the operation is
|
|
430
428
|
`queued`, `running` or `waiting_input` - only when `queued` with `queued_only`. With an open dialog
|