taskwire 0.1.0__py3-none-any.whl

taskwire/transport.py

@@ -0,0 +1,95 @@
+"""The transport port (§2.13) and the two implementations that need no optional dependency.
+
+A transport is an **accelerator**, never a source of truth (TW-CORE-002). Everything here may fail,
+drop, coalesce or refuse, and the only consequence is latency: the state was written to the store
+before any of this ran (TW-CORE-001), so a later read returns the same answer either way.
+
+That is why `notify()` may never raise (TW-TR-002) and may never block past `push_timeout`
+(TW-TR-003). A degradation in the accelerator must not become a stall in the operation
+(TW-INV-012).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import logging
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+
+from .models import Envelope
+from .settings import settings
+
+logger = logging.getLogger("taskwire.transport")
+
+Subscriber = Callable[[Envelope], Awaitable[None] | None]
+
+
+class TaskwireTransport(ABC):
+    """TW-TR-001: exactly one abstract method, plus an optional hint that is never load-bearing.
+
+    `notify` takes a namespace and an envelope and nothing else (TW-TR-004). There is deliberately
+    no list of interested connections anywhere in this design: the fan-out unit is the namespace,
+    which is also the security unit, and a per-token subscription mechanism has a startup race and
+    leaks (TW-BP-002).
+    """
+
+    @abstractmethod
+    async def notify(self, session: str, envelope: Envelope) -> None:
+        """Best-effort delivery. Never raises, never blocks past `settings.push_timeout`."""
+
+    async def is_online(self, session: str) -> bool:  # noqa: ARG002 - specified signature
+        """A hint, and never load-bearing. Defaults to True (TW-TR-001)."""
+        return True
+
+
+class NullTransport(TaskwireTransport):
+    """The baseline. Polling does all the work and every feature still works (TW-TR-007)."""
+
+    async def notify(self, _session: str, _envelope: Envelope) -> None:
+        return None
+
+
+class LocalTransport(TaskwireTransport):
+    """In-process delivery: no wire, no socket, no serialization step (TW-TR-008).
+
+    This is a first-class deployment rather than a test double. An application that never leaves its
+    own process - a browser-only front end, a single back-end service - uses every feature of
+    taskwire through this transport and needs nothing else installed (TW-SYM-001).
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, list[Subscriber]] = {}
+
+    def subscribe(self, ns: str, callback: Subscriber) -> Callable[[], None]:
+        """Register `callback` for one namespace. Returns the unsubscribe."""
+        self._subscribers.setdefault(ns, []).append(callback)
+
+        def unsubscribe() -> None:
+            handlers = self._subscribers.get(ns)
+            if handlers and callback in handlers:
+                handlers.remove(callback)
+
+        return unsubscribe
+
+    async def notify(self, session: str, envelope: Envelope) -> None:
+        """Deliver to every subscriber of `session`, in registration order.
+
+        TW-TR-009: each subscriber receives a document **no other party retains a reference to**.
+        In-process delivery is the one path where a live reference could leak where a wire transport
+        would have copied, and a subscriber that mutated what it received would otherwise be able to
+        alter the store, another subscriber's copy, or what a later read returns. TW-CORE-002 has to
+        hold identically on every transport, so the copy is not defensive tidiness - it is the rule.
+
+        TW-TR-010: a subscriber that raises, or that outlasts `push_timeout`, is a dropped push. It
+        does not propagate, it does not reach the reporter, and it does not stop the remaining
+        subscribers from being called.
+        """
+        for callback in list(self._subscribers.get(session, ())):
+            try:
+                result = callback(copy.deepcopy(envelope))
+                if asyncio.iscoroutine(result):
+                    await asyncio.wait_for(result, timeout=settings.push_timeout)
+            except Exception:  # noqa: BLE001 - a dropped push is the defined outcome, not an error
+                logger.debug("taskwire: local subscriber dropped a push", exc_info=True)

taskwire-0.1.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: taskwire
+Version: 0.1.0
+Summary: Progress reporting and awaitable dialogs for long-running server-side operations.
+Project-URL: Homepage, https://github.com/velis74/taskwire
+Project-URL: Repository, https://github.com/velis74/taskwire
+Project-URL: Issues, https://github.com/velis74/taskwire/issues
+Project-URL: Documentation, https://docs.velis.si/taskwire/
+Author-email: Jure Erznožnik <jure.erznoznik@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: celery,dialogs,dynamicforms,fastapi,progress,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == 'celery'
+Requires-Dist: nest-asyncio>=1.6; extra == 'celery'
+Provides-Extra: demo
+Requires-Dist: uvicorn>=0.27; extra == 'demo'
+Provides-Extra: dev
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: muxws
+Requires-Dist: dynamicforms-fastapi-viewsets[muxws]>=0.5.4; extra == 'muxws'
+Requires-Dist: muxws>=0.3.1; extra == 'muxws'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: viewsets
+Requires-Dist: dynamicforms-fastapi-viewsets>=0.5.4; extra == 'viewsets'
+Description-Content-Type: text/markdown
+
+# <img src="taskwire-icon.svg" alt="" style="width:2.5em; height: 2.5em; vertical-align: middle"> taskwire
+
+Progress reporting and awaitable dialogs for long-running operations, in Python and TypeScript.
+
+A long-running job — an import, a report, a batch — needs to tell whoever started it what it is
+doing while it is doing it, and sometimes needs to ask them something before it can continue.
+taskwire is that conversation, and the four things it carries:
+
+- **progress**, with nested subtasks whose percentages compose correctly rather than overwriting
+  each other, and commits coalesced so a tight loop cannot flood anything;
+- **awaitable dialogs** — the worker asks a question mid-job and blocks until the answer arrives,
+  with the first answer winning across every tab that is looking;
+- **cancellation**, cooperative and sticky, which raises in the worker at its next progress call;
+- **collectable results** — the job parks a file or a value for later collection and *exits*,
+  holding no worker while the record waits.
+
+## The one idea worth knowing
+
+**The store is the truth; a push is only an accelerator.** Every state change is written before
+anything is sent anywhere, so a dropped, coalesced or suppressed push never changes what the next
+read returns. There is no event log, no sequence numbers and no replay: a client is entitled to
+current state, and asking for it is always enough.
+
+## One protocol, three implementations
+
+The layering is the shape of the source tree:
+
+```
+             protocol            documents, envelopes, the six kinds, the state
+                 │               machines, validation.  Knows of no transport.
+     ┌───────────┼───────────┐
+   local        REST         WS         three independent implementations of it
+     │           │           │
+  (none)   fastapi / asgi   muxws       one adapter each, to the world outside
+```
+
+The **protocol** is specified once and depends on nothing. Each **implementation** carries it over
+one medium and is written against the protocol layer alone, never against another implementation.
+Each **adapter** is the thin piece that binds an implementation to a particular framework, and is
+the only place that framework is imported.
+
+| Implementation | Carries the protocol over | Adapter | Needs |
+|---|---|---|---|
+| **local** | the process itself — no wire, no socket, no serialization | none | nothing |
+| **REST** | request/response polling; the baseline everywhere | `contrib.viewsets`, `contrib.fastapi`, `contrib.asgi` | nothing in core |
+| **WS** | one push per envelope down, the six calls up, lowest latency | `contrib.muxws` | [muxws](https://docs.velis.si/muxws/) |
+
+Swapping one for another changes latency and nothing else — no feature, no state, no document.
+Both languages ship the protocol and the operating half, so a browser-only application runs
+operations rather than only watching them; the adapters, the Redis store and the Celery entry are
+Python's, and the polling client and the register are TypeScript's.
+
+## Install
+
+```bash
+pip install taskwire                 # core: no runtime dependencies at all
+pip install "taskwire[redis]"        # cross-process store and backplane
+pip install "taskwire[fastapi]"      # the REST adapter
+pip install "taskwire[viewsets]"     # the REST API as a fastapi-viewsets viewset
+pip install "taskwire[celery]"       # the worker entry point
+pip install "taskwire[muxws]"        # the WebSocket transport
+```
+
+```bash
+npm install taskwire
+```
+
+## The demo
+
+```bash
+pip install -e ".[fastapi,viewsets,demo]" && npm install
+python demo.py                       # then open http://127.0.0.1:5174
+```
+
+A night batch over one book: four back-office jobs that between them exercise progress, nested
+progress, awaitable dialogs, cancellation and collectable results. See [`demo/README.md`](demo/README.md).
+
+## Status
+
+Pre-1.0 and under active construction. The wire format is versioned independently of the package
+(`Envelope.v`), so package semver says nothing about it.
+
+## Links
+
+- [Documentation](https://docs.velis.si/taskwire/)
+- [Repository](https://github.com/velis74/taskwire)
+
+## License
+
+MIT. Copyright (c) 2026 Jure Erznožnik.

taskwire-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+taskwire/__init__.py,sha256=MhMXlE841SbzFYoXFAESm4rbZ9mz4bKt8vOK2bafLB8,3253
+taskwire/ambient.py,sha256=kIW-pQhBmEwZNxd-idKLB1WjUGgzv3bdMY2ByBXScwk,6093
+taskwire/conformance.py,sha256=XJHtZYfcPvQUiNS6okZVp9xccAtHm8v7PKbI14UwTR0,19589
+taskwire/decorators.py,sha256=6k2tkdh72TosGstPIDllq5Bo592WH2XyKJ3tvVQwfdg,3382
+taskwire/delivery.py,sha256=6Y49nHkA5dB9wX9_plaxuKd-LkK3C7qD4JqfcqrDKvQ,5068
+taskwire/headers.py,sha256=sAyz5NP9jLJIJqVM0F1MfjEy2Qrr6W_H2eCET24HcKk,1947
+taskwire/models.py,sha256=92ZGordETrudW1qJ1yilX5PI3daTHk59two8WTrtrhQ,24094
+taskwire/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+taskwire/reader.py,sha256=SoRkSD72hkREkD_KADKRVA1FK4bO58KnJNd-rFP0sRk,4996
+taskwire/register.py,sha256=MrPOk1T9xXd0-lLZW26SiMjmiWmrozBREATQJ9oJSj8,7926
+taskwire/reporter.py,sha256=sOaWeVbIz0kUKfOCbpntJwqxul6dmevSlyIrr2XRod4,51073
+taskwire/rest.py,sha256=hz6b473gAVsWVB4O0E81MexhpvRAV_pKxMgpulYbfe0,13568
+taskwire/settings.py,sha256=dbTXTSHW4mjbxdTwONjQ9xfO2wL7Vsep0hGp6heYseA,4957
+taskwire/store.py,sha256=vWGp6GGKeIKNK7SHoYFKs4lJdbDtzlhHsaJ4ZCoLngM,29346
+taskwire/transport.py,sha256=CcgkMblXsktDs92a-1w0Ueqi2y7r5oJePP4IEeYXiOc,4258
+taskwire/contrib/__init__.py,sha256=FWMUvGlCws8DERXwwmHleKVXBwnJEWnhtVKKsVr59bU,694
+taskwire/contrib/asgi.py,sha256=lWtWVAq9w-APL61gvr-BG0uaRQlqu2lV4Re40SJTsk4,3755
+taskwire/contrib/celery.py,sha256=DW0Vik0l02xur6zjMTu8Ai6LwIXqeTi8aFj8Gn9vzM8,17709
+taskwire/contrib/fastapi.py,sha256=I8Mjpy1tTxvlXTJHYh0USaB4eIUHgShegvULHdf7Uzs,3639
+taskwire/contrib/muxws.py,sha256=Uum48s2vWAbtiHfrePy2tnx9O03B7x-5zkmL00VtCeQ,18548
+taskwire/contrib/redis_store.py,sha256=5Bany9xrd5bo489m8timmHvtTT-G0t3k4zXrgNUX2r0,24350
+taskwire/contrib/schema.py,sha256=-I2bd3Us6igAFULml-D-e_fGzbC69xSipFCCOiOcRpQ,7147
+taskwire/contrib/threads.py,sha256=qxypMRqXzsXUzzUpsfTzJLVsn1OPtByJtFhg65mz9CA,1466
+taskwire/contrib/viewsets.py,sha256=G3bZVgRb2Fqf6UHyHclkSTcg2JZkIcFnA2f6iIUi1_A,14824
+taskwire-0.1.0.dist-info/METADATA,sha256=fmButJRdTKmB3nTXrBblUSxgOVELdgdz0e0Wpn8JGcA,6240
+taskwire-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+taskwire-0.1.0.dist-info/licenses/LICENSE,sha256=g5DUzLsev_7tQp4RFbAQVfqnmRlk9cu_ZE60o6vuPs4,1072
+taskwire-0.1.0.dist-info/RECORD,,

taskwire-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

taskwire-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jure Erznožnik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.