offwork 0.1.3__tar.gz → 0.2.0__tar.gz

{offwork-0.1.3 → offwork-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: offwork
-Version: 0.1.3
+Version: 0.2.0
 Summary: Distributed Python task execution via automatic function serialization
 License: AGPL-3.0-only
 License-File: LICENSE
@@ -20,8 +20,10 @@ Classifier: Topic :: System :: Distributed Computing
 Classifier: Typing :: Typed
 Provides-Extra: rabbitmq
 Provides-Extra: redis
+Provides-Extra: ws
 Requires-Dist: aio-pika (>=9.0) ; extra == "rabbitmq"
 Requires-Dist: redis (>=5.0) ; extra == "redis"
+Requires-Dist: websockets (>=15.0) ; extra == "ws"
 Project-URL: Repository, https://github.com/codeSamuraii/offwork
 Description-Content-Type: text/markdown
 
@@ -76,21 +78,21 @@ pip install offwork[redis]
 offwork worker --backend redis://other-machine:6379
 ```
 
-See [Features](docs/FEATURES.md) for the full API.
-
 ## Features
 
 | | |
 |-|-|
-| **Async-native** | `.run()`, `.start()`, `.map()`, `asyncio.gather` — all coroutines |
-| **Scheduling** | `.run_in(delay)`, `.run_at(datetime)`, `.run_every(interval)` with cancellation |
+| **Async-native** | `.run()`, `.submit()`, `.map()`, `asyncio.gather` — all coroutines |
+| **Scheduling** | `submit(run_in=delay)`, `submit(run_at=dt)`, `submit(run_every=interval)` with cancellation |
 | **Retry & timeout** | `@offwork.task(timeout=30, retries=3)` with exponential backoff |
 | **Throttling** | `@offwork.task(throttle=timedelta(hours=24)/50)` — rate-limit executions |
-| **Progress & cancellation** | `offwork.progress(3, 10)` inside tasks; `await future.cancel()` on client |
+| **Progress & cancellation** | `offwork.progress(3, 10)` inside tasks; `fut.cancel()` / `await fut.cancel()` on client |
 | **Heartbeat & stall detection** | Workers heartbeat every second; clients raise `TaskStalled` on silence |
 | **Package auto-install** | Workers `pip install` missing packages before execution |
 | **Docker sandbox** | Optional container isolation, fully transparent to clients |
 | **Signed execution** | Pre-shared token or PIN pairing + HMAC-SHA256 task authentication |
+| ... | See [Features](docs/FEATURES.md) for more information. |
+
 
 ### Security
 

{offwork-0.1.3 → offwork-0.2.0}/README.md

@@ -49,21 +49,21 @@ pip install offwork[redis]
 offwork worker --backend redis://other-machine:6379
 ```
 
-See [Features](docs/FEATURES.md) for the full API.
-
 ## Features
 
 | | |
 |-|-|
-| **Async-native** | `.run()`, `.start()`, `.map()`, `asyncio.gather` — all coroutines |
-| **Scheduling** | `.run_in(delay)`, `.run_at(datetime)`, `.run_every(interval)` with cancellation |
+| **Async-native** | `.run()`, `.submit()`, `.map()`, `asyncio.gather` — all coroutines |
+| **Scheduling** | `submit(run_in=delay)`, `submit(run_at=dt)`, `submit(run_every=interval)` with cancellation |
 | **Retry & timeout** | `@offwork.task(timeout=30, retries=3)` with exponential backoff |
 | **Throttling** | `@offwork.task(throttle=timedelta(hours=24)/50)` — rate-limit executions |
-| **Progress & cancellation** | `offwork.progress(3, 10)` inside tasks; `await future.cancel()` on client |
+| **Progress & cancellation** | `offwork.progress(3, 10)` inside tasks; `fut.cancel()` / `await fut.cancel()` on client |
 | **Heartbeat & stall detection** | Workers heartbeat every second; clients raise `TaskStalled` on silence |
 | **Package auto-install** | Workers `pip install` missing packages before execution |
 | **Docker sandbox** | Optional container isolation, fully transparent to clients |
 | **Signed execution** | Pre-shared token or PIN pairing + HMAC-SHA256 task authentication |
+| ... | See [Features](docs/FEATURES.md) for more information. |
+
 
 ### Security
 

{offwork-0.1.3 → offwork-0.2.0}/offwork/__init__.py

@@ -62,7 +62,8 @@ from offwork.core.envelope import (
 from offwork.core.version import _VERSION
 from offwork.core.progress import ProgressInfo
 from offwork.core.progress import progress as progress
-from offwork.worker.remote import serve, connect, disconnect
+from offwork.core._timeout import TimeoutIn, WaitForever, ReturnImmediately
+from offwork.worker.remote import serve, connect, disconnect, _ConnectionContext
 from offwork.worker.result import Result, ResultEnvelope
 from offwork.worker.worker import Worker
 from offwork.worker.worker import execute as execute
@@ -129,6 +130,12 @@ __all__ = [
     "install_package_as",
     "worker_only_import",
     "progress",
+    # Timeout types
+    "TimeoutIn",
+    "WaitForever",
+    "ReturnImmediately",
+    # Connection handle
+    "_ConnectionContext",
     # Serialization
     "serialize",
     "reconstruct",

offwork-0.2.0/offwork/core/_timeout.py

@@ -0,0 +1,60 @@
+"""Shared timeout type and resolution helper used across the public API."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Literal
+
+# ── Named sentinels ──────────────────────────────────────────────────────────
+
+type WaitForever = Literal[False] | Literal[-1]
+"""Sentinel: block until the operation completes, with no deadline."""
+
+type ReturnImmediately = Literal[True] | Literal[0]
+"""Sentinel: return as soon as possible (non-blocking / fast-poll)."""
+
+# ── Public timeout type ───────────────────────────────────────────────────────
+
+type TimeoutIn = float | timedelta | WaitForever | ReturnImmediately
+"""A duration accepted by every wait-style method in the public API.
+
+Interpretation
+--------------
+``False`` or ``-1``
+    Block indefinitely until the operation completes.
+``True`` or ``0``
+    Return as soon as possible (non-blocking or single fast poll).
+``timedelta``
+    Wait at most this duration.
+``float`` (positive)
+    Wait at most this many seconds.
+"""
+
+
+# ── Internal helper ───────────────────────────────────────────────────────────
+
+def resolve_timeout(t: TimeoutIn) -> float | None:
+    """Convert a :data:`TimeoutIn` value to seconds (``float``) or ``None``.
+
+    Returns
+    -------
+    None
+        Wait forever (corresponds to ``False`` or ``-1``).
+    0.0
+        Non-blocking / return immediately (corresponds to ``True`` or ``0``).
+    positive float
+        Maximum seconds to wait.
+    """
+    # bool is a subtype of int — check identity before numeric equality
+    # so that False is not mistaken for 0 and True is not mistaken for 1.
+    if t is False:
+        return None
+    if t is True:
+        return 0.0
+    if t == -1:
+        return None
+    if t == 0:
+        return 0.0
+    if isinstance(t, timedelta):
+        return t.total_seconds()
+    return float(t)

{offwork-0.1.3 → offwork-0.2.0}/offwork/core/envelope.py

@@ -171,6 +171,8 @@ def verify_task_envelope(
         retry_delay=data.get("retry_delay", 1.0),
         scheduled_at=data.get("scheduled_at"),
         recur_interval=data.get("recur_interval"),
+        recur_deadline=data.get("recur_deadline"),
+        recur_remaining=data.get("recur_remaining"),
         schedule_id=data.get("schedule_id"),
         throttle=data.get("throttle"),
     )

{offwork-0.1.3 → offwork-0.2.0}/offwork/core/task.py

@@ -418,6 +418,8 @@ class Task:
     retry_delay: float = 1.0
     scheduled_at: float | None = None
     recur_interval: float | None = None
+    recur_deadline: float | None = None
+    recur_remaining: int | None = None
     schedule_id: str | None = None
     throttle: float | None = None
 
@@ -442,6 +444,10 @@ class Task:
             d["scheduled_at"] = self.scheduled_at
         if self.recur_interval is not None:
             d["recur_interval"] = self.recur_interval
+        if self.recur_deadline is not None:
+            d["recur_deadline"] = self.recur_deadline
+        if self.recur_remaining is not None:
+            d["recur_remaining"] = self.recur_remaining
         if self.schedule_id is not None:
             d["schedule_id"] = self.schedule_id
         if self.throttle is not None:
@@ -467,6 +473,8 @@ class Task:
             retry_delay=data.get("retry_delay", 1.0),
             scheduled_at=data.get("scheduled_at"),
             recur_interval=data.get("recur_interval"),
+            recur_deadline=data.get("recur_deadline"),
+            recur_remaining=data.get("recur_remaining"),
             schedule_id=data.get("schedule_id"),
             throttle=data.get("throttle"),
         )

{offwork-0.1.3 → offwork-0.2.0}/offwork/graph/tracing.py

@@ -28,39 +28,141 @@ _R = TypeVar("_R")
 _BUILTIN_NAMES = set(dir(builtins))
 
 
-def _make_start_method(
+def _make_submit_method(
     wrapper: Callable[..., object], func: Callable[..., object]
 ) -> Callable[..., object]:
-    """Create the ``.start()`` async method that submits and returns a Result."""
+    """Create the ``.submit()`` async method.
+
+    Submits the function to a remote worker and returns a :class:`Result`
+    handle (or a :class:`ScheduleHandle` when *run_every* is set).
+
+    Scheduling keywords (all optional, at most one of ``run_at`` /
+    ``run_in`` / ``run_every`` may be given):
+
+    ``run_at``
+        :class:`~datetime.datetime` — run once at a specific point in time.
+    ``run_in``
+        :class:`~datetime.timedelta` or ``float`` (seconds) — run once after
+        a delay.
+    ``run_every``
+        :class:`~datetime.timedelta` or ``float`` (seconds) — repeat at this
+        interval.  Returns a :class:`ScheduleHandle` instead of a
+        :class:`Result`.
+
+    Additional keywords for recurring schedules:
+
+    ``_start_at``
+        :class:`~datetime.datetime` — first occurrence for *run_every*.
+    ``run_for``
+        :class:`~datetime.timedelta` or ``float`` (seconds) — stop recurring
+        after this wall-clock duration.
+    ``max_runs``
+        ``int`` — stop recurring after this many executions.
+    ``backend``
+        Override the global backend for this submission.
+    """
+
+    async def submit(
+        *args: Any,
+        run_at: datetime | None = None,
+        run_in: timedelta | float | None = None,
+        run_every: timedelta | float | None = None,
+        _start_at: datetime | None = None,
+        run_for: timedelta | float | None = None,
+        max_runs: int | None = None,
+        backend: str | Backend | None = None,
+        **kwargs: Any,
+    ) -> object:
+        if sum(x is not None for x in (run_at, run_in, run_every)) > 1:
+            raise ValueError(
+                "At most one of run_at, run_in, run_every may be specified"
+            )
+
+        if run_every is not None:
+            from offwork.worker.remote import submit_recurring  # circular
+
+            interval = (
+                run_every.total_seconds()
+                if isinstance(run_every, timedelta)
+                else float(run_every)
+            )
+            start_ts: float | None = None
+            if _start_at is not None:
+                start_ts = (
+                    _start_at.timestamp()
+                    if isinstance(_start_at, datetime)
+                    else float(_start_at)
+                )
+            if run_for is None and max_runs is None:
+                run_for = timedelta(hours=1)
+            run_for_seconds: float | None = None
+            if run_for is not None:
+                run_for_seconds = (
+                    run_for.total_seconds()
+                    if isinstance(run_for, timedelta)
+                    else float(run_for)
+                )
+                if run_for_seconds <= 0:
+                    raise ValueError(f"run_for must be positive, got {run_for}")
+            if max_runs is not None and max_runs <= 0:
+                raise ValueError(f"max_runs must be positive, got {max_runs}")
+            return await submit_recurring(
+                func, wrapper, *args,
+                _backend=backend, _interval=interval, _start_at=start_ts,
+                _run_for=run_for_seconds, _max_runs=max_runs,
+                **kwargs,
+            )
+
+        if run_at is not None or run_in is not None:
+            from offwork.worker.remote import submit_remote_scheduled  # circular
+
+            if run_at is not None:
+                scheduled_at = (
+                    run_at.timestamp()
+                    if isinstance(run_at, datetime)
+                    else float(run_at)
+                )
+            else:
+                assert run_in is not None
+                delay = (
+                    run_in.total_seconds()
+                    if isinstance(run_in, timedelta)
+                    else float(run_in)
+                )
+                scheduled_at = _time.time() + delay
+            return await submit_remote_scheduled(
+                func, wrapper, *args,
+                _backend=backend, _scheduled_at=scheduled_at,
+                **kwargs,
+            )
 
-    async def start(*args: Any, backend: str | Backend | None = None, **kwargs: Any) -> object:
         from offwork.worker.remote import submit_remote  # circular
 
         return await submit_remote(func, wrapper, *args, _backend=backend, **kwargs)
 
-    return start
+    return submit
 
 
 def _make_run_method(
-    start_method: Callable[..., object],
+    submit_method: Callable[..., object],
 ) -> Callable[..., object]:
     """Create the ``.run()`` async method that submits and awaits the result."""
 
     async def run(*args: object, **kwargs: object) -> object:
-        result = await start_method(*args, **kwargs)  # type: ignore[misc]
+        result = await submit_method(*args, **kwargs)  # type: ignore[misc]
         return await result
 
     return run
 
 
 def _make_map_method(
-    start_method: Callable[..., object],
+    submit_method: Callable[..., object],
 ) -> Callable[..., object]:
     """Create the ``.map()`` async method for batch submission and collection."""
 
     async def map(args_list: list[tuple[object, ...]], **kwargs: object) -> list[object]:
         coros: list[Awaitable[object]] = [
-            cast(Awaitable[object], start_method(*args, **kwargs))
+            cast(Awaitable[object], submit_method(*args, **kwargs))
             for args in args_list
         ]
         results = await asyncio.gather(*coros)
@@ -72,108 +174,15 @@ def _make_map_method(
     return map
 
 
-def _make_start_at_method(
-    wrapper: Callable[..., object], func: Callable[..., object]
-) -> Callable[..., object]:
-    """Create the ``.start_at()`` method that submits a task scheduled for a specific time."""
-
-    async def start_at(dt: Any, *args: Any, backend: str | Backend | None = None, **kwargs: Any) -> object:
-        from offwork.worker.remote import submit_remote_scheduled  # circular
-
-        ts = dt.timestamp() if isinstance(dt, datetime) else float(dt)
-        return await submit_remote_scheduled(
-            func, wrapper, *args, _backend=backend, _scheduled_at=ts, **kwargs,
-        )
-
-    return start_at
-
-
-def _make_run_at_method(
-    start_at_method: Callable[..., object],
-) -> Callable[..., object]:
-    """Create the ``.run_at()`` method that submits at a time and awaits the result."""
-
-    async def run_at(dt: Any, *args: object, **kwargs: object) -> object:
-        result = await start_at_method(dt, *args, **kwargs)  # type: ignore[misc]
-        return await result
-
-    return run_at
-
-
-def _make_start_in_method(
-    wrapper: Callable[..., object], func: Callable[..., object]
-) -> Callable[..., object]:
-    """Create the ``.start_in()`` method that submits a task after a delay."""
-
-    async def start_in(delay: Any, *args: Any, backend: str | Backend | None = None, **kwargs: Any) -> object:
-        from offwork.worker.remote import submit_remote_scheduled  # circular
-
-        seconds = delay.total_seconds() if isinstance(delay, timedelta) else float(delay)
-        return await submit_remote_scheduled(
-            func, wrapper, *args, _backend=backend, _scheduled_at=_time.time() + seconds, **kwargs,
-        )
-
-    return start_in
-
-
-def _make_run_in_method(
-    start_in_method: Callable[..., object],
-) -> Callable[..., object]:
-    """Create the ``.run_in()`` method that submits after a delay and awaits."""
-
-    async def run_in(delay: Any, *args: object, **kwargs: object) -> object:
-        result = await start_in_method(delay, *args, **kwargs)  # type: ignore[misc]
-        return await result
-
-    return run_in
-
-
-def _make_run_every_method(
-    wrapper: Callable[..., object], func: Callable[..., object]
-) -> Callable[..., object]:
-    """Create the ``.run_every()`` method for recurring execution."""
-
-    async def run_every(
-        frequency: Any,
-        *args: Any,
-        _start_at: Any = None,
-        backend: str | Backend | None = None,
-        **kwargs: Any,
-    ) -> object:
-        from offwork.worker.remote import submit_recurring  # circular
-
-        interval = frequency.total_seconds() if isinstance(frequency, timedelta) else float(frequency)
-        start_ts: float | None = None
-        if _start_at is not None:
-            start_ts = _start_at.timestamp() if isinstance(_start_at, datetime) else float(_start_at)
-        return await submit_recurring(
-            func, wrapper, *args,
-            _backend=backend, _interval=interval, _start_at=start_ts,
-            **kwargs,
-        )
-
-    return run_every
-
-
 def _attach_traced_attrs(
     wrapper: Callable[..., object], func: Callable[..., object]
 ) -> None:
-    """Attach offwork metadata and .start()/.run()/.map() to a traced wrapper."""
+    """Attach offwork metadata and remote-execution methods to a traced wrapper."""
     wrapper.__offwork_traced__ = True  # type: ignore[attr-defined]
-    start = _make_start_method(wrapper, func)
-    wrapper.start = start  # type: ignore[attr-defined]
-    wrapper.run = _make_run_method(start)  # type: ignore[attr-defined]
-    wrapper.map = _make_map_method(start)  # type: ignore[attr-defined]
-
-    start_at = _make_start_at_method(wrapper, func)
-    wrapper.start_at = start_at  # type: ignore[attr-defined]
-    wrapper.run_at = _make_run_at_method(start_at)  # type: ignore[attr-defined]
-
-    start_in = _make_start_in_method(wrapper, func)
-    wrapper.start_in = start_in  # type: ignore[attr-defined]
-    wrapper.run_in = _make_run_in_method(start_in)  # type: ignore[attr-defined]
-
-    wrapper.run_every = _make_run_every_method(wrapper, func)  # type: ignore[attr-defined]
+    submit = _make_submit_method(wrapper, func)
+    wrapper.submit = submit  # type: ignore[attr-defined]
+    wrapper.run = _make_run_method(submit)  # type: ignore[attr-defined]
+    wrapper.map = _make_map_method(submit)  # type: ignore[attr-defined]
 
 
 def _get_stdlib_dirs() -> list[str]:

offwork-0.2.0/offwork/typing.py

@@ -0,0 +1,126 @@
+"""Protocol types for ``@offwork.task``-decorated functions."""
+
+from datetime import datetime, timedelta
+from typing import Any, TypeVar, Protocol, ParamSpec, overload
+from collections.abc import Callable
+
+from offwork.worker.result import Result
+from offwork.worker.schedule import ScheduleHandle
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class TracedFunction(Protocol[P, R]):
+    """A function decorated with ``@offwork.task``, with remote execution methods.
+
+    Direct call
+    -----------
+    Calling the function normally (``func(*args)``) executes it locally,
+    exactly as if ``@offwork.task`` were not present.
+
+    Remote execution
+    ----------------
+    :meth:`submit`
+        Submit to a remote worker; return a :class:`~offwork.Result` handle.
+        Pass scheduling keywords to run once in the future or on a recurring
+        schedule (returns :class:`~offwork.ScheduleHandle` when *run_every*
+        is given).
+    :meth:`run`
+        Submit and ``await`` the result in one call.
+    :meth:`map`
+        Submit the same function with multiple argument-tuples in parallel.
+    """
+
+    __offwork_traced__: bool
+    __wrapped__: Callable[P, R]
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R: ...
+
+    # -- overload: run_every present → ScheduleHandle -------------------------
+
+    @overload
+    async def submit(
+        self,
+        *args: Any,
+        run_every: timedelta | float,
+        run_at: None = ...,
+        run_in: None = ...,
+        _start_at: datetime | None = ...,
+        run_for: timedelta | float | None = ...,
+        max_runs: int | None = ...,
+        backend: Any = ...,
+        **kwargs: Any,
+    ) -> ScheduleHandle: ...
+
+    # -- overload: no run_every → Result ---------------------------------------
+
+    @overload
+    async def submit(
+        self,
+        *args: Any,
+        run_every: None = ...,
+        run_at: datetime | None = ...,
+        run_in: timedelta | float | None = ...,
+        backend: Any = ...,
+        **kwargs: Any,
+    ) -> Result: ...
+
+    async def submit(self, *args: Any, **kwargs: Any) -> Result | ScheduleHandle:
+        """Submit the function to a remote worker.
+
+        Parameters
+        ----------
+        *args
+            Positional arguments forwarded to the function.
+        run_at
+            :class:`~datetime.datetime` — schedule a one-shot run at this
+            point in time.
+        run_in
+            :class:`~datetime.timedelta` or ``float`` (seconds) — schedule
+            a one-shot run after this delay.
+        run_every
+            :class:`~datetime.timedelta` or ``float`` (seconds) — run on a
+            recurring schedule at this interval.  Returns a
+            :class:`~offwork.ScheduleHandle` instead of a :class:`~offwork.Result`.
+        _start_at
+            First occurrence for *run_every* schedules.
+        run_for
+            Stop recurring after this wall-clock duration (*run_every* only).
+        max_runs
+            Stop recurring after this many executions (*run_every* only).
+        backend
+            Override the global backend for this submission.
+        **kwargs
+            Keyword arguments forwarded to the function.
+
+        Returns
+        -------
+        Result
+            When called without *run_every*.
+        ScheduleHandle
+            When called with *run_every*.
+        """
+        ...
+
+    async def run(self, *args: P.args, **kwargs: P.kwargs) -> Any:
+        """Submit and immediately ``await`` the result.
+
+        Equivalent to ``await (await func.submit(*args, **kwargs))``.
+        """
+        ...
+
+    async def map(self, args_list: list[tuple[Any, ...]], **kwargs: Any) -> list[Any]:
+        """Submit the function for each argument-tuple and collect all results.
+
+        Equivalent to::
+
+            await asyncio.gather(*(func.run(*a, **kwargs) for a in args_list))
+        """
+        ...
+
+
+class TraceDecorator(Protocol):
+    """The ``@offwork.task`` decorator when called with keyword arguments."""
+
+    def __call__(self, func: Callable[P, R]) -> TracedFunction[P, R]: ...

{offwork-0.1.3 → offwork-0.2.0}/offwork/worker/backends/base.py

@@ -41,6 +41,17 @@ class Backend(abc.ABC):
         heartbeat-based stall detection should override this.
         """
 
+    async def heartbeat_and_check_cancel(self, task_id: str) -> bool:
+        """Send a heartbeat and return whether the task is cancelled.
+
+        Backends with a single round-trip combining both (e.g. an
+        HTTP POST whose response carries the cancel flag) should
+        override this to halve worker→broker chatter while a task is
+        running. The default implementation issues two calls.
+        """
+        await self.send_heartbeat(task_id)
+        return await self.is_cancelled(task_id)
+
     async def get_heartbeat(self, task_id: str) -> float | None:
         """Return the timestamp of the last heartbeat for *task_id*.