taskwire 0.4.4__tar.gz → 0.5.0__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.
Files changed (75) hide show
  1. {taskwire-0.4.4 → taskwire-0.5.0}/PKG-INFO +21 -38
  2. taskwire-0.5.0/README.md +73 -0
  3. taskwire-0.5.0/conformance/README.md +9 -0
  4. {taskwire-0.4.4 → taskwire-0.5.0}/pyproject.toml +3 -4
  5. {taskwire-0.4.4 → taskwire-0.5.0}/pyproject.toml.orig +20 -31
  6. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/__init__.py +7 -7
  7. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/ambient.py +16 -22
  8. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/calls.py +4 -6
  9. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/conformance.py +31 -66
  10. taskwire-0.5.0/taskwire/contrib/__init__.py +14 -0
  11. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/contrib/asgi.py +17 -22
  12. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/contrib/celery.py +29 -50
  13. taskwire-0.5.0/taskwire/contrib/fastapi.py +144 -0
  14. taskwire-0.5.0/taskwire/contrib/muxws.py +300 -0
  15. taskwire-0.5.0/taskwire/contrib/openapi.py +141 -0
  16. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/contrib/redis_store.py +35 -66
  17. taskwire-0.5.0/taskwire/contrib/schema.py +301 -0
  18. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/contrib/threads.py +6 -9
  19. taskwire-0.5.0/taskwire/contrib/viewsets.py +383 -0
  20. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/contrib/viewsets_events.py +9 -6
  21. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/decorators.py +17 -23
  22. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/delivery.py +26 -34
  23. taskwire-0.5.0/taskwire/headers.py +25 -0
  24. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/models.py +57 -39
  25. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/publish.py +2 -3
  26. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/reader.py +16 -33
  27. taskwire-0.5.0/taskwire/register.py +134 -0
  28. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/reporter.py +126 -297
  29. taskwire-0.5.0/taskwire/rest.py +345 -0
  30. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/settings.py +10 -21
  31. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/store.py +72 -154
  32. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/transport.py +16 -29
  33. taskwire-0.4.4/README.md +0 -90
  34. taskwire-0.4.4/conformance/README.md +0 -10
  35. taskwire-0.4.4/taskwire/contrib/__init__.py +0 -17
  36. taskwire-0.4.4/taskwire/contrib/fastapi.py +0 -82
  37. taskwire-0.4.4/taskwire/contrib/muxws.py +0 -361
  38. taskwire-0.4.4/taskwire/contrib/schema.py +0 -231
  39. taskwire-0.4.4/taskwire/contrib/viewsets.py +0 -529
  40. taskwire-0.4.4/taskwire/headers.py +0 -36
  41. taskwire-0.4.4/taskwire/register.py +0 -182
  42. taskwire-0.4.4/taskwire/rest.py +0 -365
  43. {taskwire-0.4.4 → taskwire-0.5.0}/LICENSE +0 -0
  44. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/exception-names.json +0 -0
  45. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/sequences/.gitkeep +0 -0
  46. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/aggregate-counts.json +0 -0
  47. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/aggregate-waiting-input-dominates.json +0 -0
  48. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/dialog-request-open.json +0 -0
  49. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/envelope-cancel.json +0 -0
  50. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/envelope-progress.json +0 -0
  51. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/envelope-snapshot.json +0 -0
  52. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/error-dispatch-failed.json +0 -0
  53. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-percent-absent.json +0 -0
  54. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-percent-null.json +0 -0
  55. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-private.json +0 -0
  56. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-shared-origins.json +0 -0
  57. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-state-cancelled.json +0 -0
  58. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-state-done.json +0 -0
  59. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-state-failed.json +0 -0
  60. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-state-queued.json +0 -0
  61. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-state-running.json +0 -0
  62. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/progress-state-waiting-input.json +0 -0
  63. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/register-empty-null-aggregate.json +0 -0
  64. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/register-v2-with-aggregate.json +0 -0
  65. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/result-kind-and-params.json +0 -0
  66. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/result-label-and-value-no-ref.json +0 -0
  67. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/result-ref-with-expires-at.json +0 -0
  68. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/snapshot-v2-wall-clock-rev.json +0 -0
  69. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/snapshot-waiting-input-uncollected-result.json +0 -0
  70. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/text-key-and-text.json +0 -0
  71. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/text-key-only.json +0 -0
  72. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/text-key-params-and-text.json +0 -0
  73. {taskwire-0.4.4 → taskwire-0.5.0}/conformance/wire/text-text-only.json +0 -0
  74. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/contrib/wsgi.py +0 -0
  75. {taskwire-0.4.4 → taskwire-0.5.0}/taskwire/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: taskwire
3
- Version: 0.4.4
3
+ Version: 0.5.0
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.13.0 ; extra == 'muxws'
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.13.0 ; extra == 'viewsets'
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 is that conversation, and the four things it carries:
45
+ taskwire provides:
46
46
 
47
- - **progress**, with nested subtasks whose percentages compose correctly rather than overwriting
48
- each other, and commits coalesced so a tight loop cannot flood anything;
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 that is looking;
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 *exits*,
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 one idea worth knowing
55
+ ## The store holds the state
56
56
 
57
- **The store is the truth; a push is only an accelerator.** Every state change is written before
58
- anything is sent anywhere, so a dropped, coalesced or suppressed push never changes what the next
59
- read returns. There is no event log, no sequence numbers and no replay: a client is entitled to
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
- | **local** | the process itself — no wire, no socket, no serialization | none | nothing |
83
- | **REST** | request/response polling; the baseline everywhere | `contrib.viewsets`, `contrib.fastapi`, `contrib.asgi` | nothing in core |
84
- | **WS** | one push per envelope down, the six calls up, lowest latency | `contrib.muxws` | [muxws](https://docs.velis.si/muxws/) |
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 and nothing else — no feature, no state, no document.
87
- Both languages ship the protocol and the operating half, so a browser-only application runs
88
- operations rather than only watching them; the adapters, the Redis store and the Celery entry are
89
- Python's, and the polling client and the register are TypeScript's.
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 at all
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 and under active construction. The wire format is versioned independently of the package
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
@@ -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.4.4"
7
+ version = "0.5.0"
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.13.0"]
46
+ viewsets = ["dynamicforms-fastapi-viewsets>=0.15.3"]
47
47
  muxws = [
48
48
  "muxws>=0.4.1",
49
- "dynamicforms-fastapi-viewsets[muxws]>=0.13.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.4.4"
7
+ version = "0.5.0"
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 = [] # DELIBERATE: core has no runtime dependency of any kind (TW-CORE-006)
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.13.0, the release the npm peer range names; from 0.12.0: namespaced error codes
34
- # (`fastapi-viewsets.<code>`), which `TaskwireMiddleware` forwards
35
- # verbatim, and one error body for every viewset route. From earlier releases: the execution hook
36
- # and the Idempotency-Key helpers; a muxws command that runs to the end of its action when its
37
- # stream ends early (TW-CALL-*); delivery filters that run on poll as on push,
38
- # which `contrib/viewsets_events.py` relies on for the display decision (TW-EVT-004); and an executor
39
- # that reports its outcomes in its own terms - `ActionInterruptedError`, `ActionOutcomeUnknownError`,
40
- # `Middleware.executor_started()` and `Middleware.on_transition()` - so that `contrib/viewsets.py`
41
- # imports no Celery (TW-CALL-101, TW-CALL-105), and that reports a process exit to `on_transition()`
42
- # in every pool.
43
- viewsets = ["dynamicforms-fastapi-viewsets>=0.13.0"]
44
- # The socket carries the six request/response calls as viewset commands (TW-REST-004), so the muxws
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
- # The release tool stamps the two manifests by itself. `vue/index.ts` is the third place the version
72
- # is written down - the npm half exports it as `VERSION` - and nothing about a Python manifest points
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` holds the normative specification and the design brief. They are prose that happens to
91
- # quote Python, and ruff would otherwise reformat the code inside their fenced blocks.
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/S106/S107 flag string literals assigned to a parameter named `token`, on the assumption that
99
- # a token is a credential. In taskwire it is the opposite: a token is an operation's *address* and
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 is only an accelerator. Every state change is written before anything
4
- is sent anywhere, so a dropped, coalesced or suppressed push never changes what the next read
5
- returns - which is what lets the transport be swapped without changing behaviour.
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
- The layering is: one **protocol** (the documents of §3 and the state machines of §4, in `models`),
8
- then three independent **implementations** of it - local (`transport.LocalTransport`), REST
9
- (`rest`), and WebSocket (`contrib.muxws`) - each with one **adapter** binding it to the world
10
- outside. Nothing in the core imports a framework, a driver or a UI library (TW-CORE-006).
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
- Deep in a call stack, threading a `Reporter` through six functions that have no other reason to know
4
- about progress is the kind of change people decline to make. The ambient proxy is the answer: bind
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
- **Python only.** TW-SYM-004 forbids a TypeScript twin: `contextvars` has no browser equivalent, and
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
- ## The trap this module exists to avoid
8
+ ## Concurrent siblings
12
9
 
13
- Concurrent siblings MUST each receive their own reporter **explicitly** (TW-NEST-014). The ambient
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, and the ranges interleave into nonsense
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 its context per task, so the `gather` form is not merely *untidy* - each task
29
- gets a snapshot of the same binding and their contributions land on one child's range.
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
- Resetting rather than overwriting is the whole rule. A raising task that merely wrote `None` back
50
- would leave the *next* task on the same pooled thread holding a stale binding, and operation A's
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
- Every method is a **silent async no-op when nothing is bound** (TW-AMB-002). Silence is the
66
- point: library code that reports progress must be callable from a caller that never opened an
67
- operation, without that caller having to care and without a warning on every line.
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
- # Still reject `state`, even unbound. Code that would be rejected inside an operation
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, there is nobody to ask and nothing to wait for, so this returns `None` rather than
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`, and is not a second mechanism."""
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
- The adapters do nothing but read a framework's request into a `Call` and place these primitives:
18
- `taskwire.contrib.asgi.track_calls`, `taskwire.contrib.wsgi.track_calls` and
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). The keyword arguments `taskwire_task` takes."""
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). For the process that observes such an end from outside the execution.
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