offwork 0.1.3__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: offwork
-Version: 0.1.3
+Version: 0.1.4
 Summary: Distributed Python task execution via automatic function serialization
 License: AGPL-3.0-only
 License-File: LICENSE

{offwork-0.1.3 → offwork-0.1.4}/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.1.4}/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.1.4}/offwork/graph/tracing.py

@@ -137,6 +137,8 @@ def _make_run_every_method(
         frequency: Any,
         *args: Any,
         _start_at: Any = None,
+        run_for: Any = None,
+        max_runs: int | None = None,
         backend: str | Backend | None = None,
         **kwargs: Any,
     ) -> object:
@@ -146,9 +148,19 @@ def _make_run_every_method(
         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,
         )
 

{offwork-0.1.3 → offwork-0.1.4}/offwork/typing.py

@@ -38,6 +38,8 @@ class TracedFunction(Protocol[P, R]):
         frequency: timedelta | float,
         *args: Any,
         _start_at: datetime | None = ...,
+        run_for: timedelta | float | None = ...,
+        max_runs: int | None = ...,
         **kwargs: Any,
     ) -> ScheduleHandle: ...
 

{offwork-0.1.3 → offwork-0.1.4}/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*.
 

{offwork-0.1.3 → offwork-0.1.4}/offwork/worker/backends/http.py

@@ -171,6 +171,12 @@ class HttpBackend(Backend):
     async def send_heartbeat(self, task_id: str) -> None:
         await self._request("POST", f"/tasks/{task_id}/heartbeat")
 
+    async def heartbeat_and_check_cancel(self, task_id: str) -> bool:
+        _status, body = await self._request(
+            "POST", f"/tasks/{task_id}/heartbeat", allow_not_found=True,
+        )
+        return bool(body and body.get("cancelled"))
+
     async def get_heartbeat(self, task_id: str) -> float | None:
         _status, body = await self._request(
             "GET", f"/tasks/{task_id}/heartbeat", allow_not_found=True,

{offwork-0.1.3 → offwork-0.1.4}/offwork/worker/deps.py

@@ -325,6 +325,14 @@ async def install_packages(
             result.failed[module] = stderr.strip()
             logger.error("Failed to install %s: %s", package, stderr.strip()[:200])
 
+    if result.installed:
+        # Drop importlib's cached "this directory doesn't exist / has no such
+        # module" entries so the next ``find_spec``/``import`` picks up files
+        # pip just wrote. Required when the target site-packages directory
+        # was created at install time (e.g. an emptyDir volume mounted over
+        # an empty user-site).
+        importlib.invalidate_caches()
+
     _raise_on_failures(result.failed)
     return result
 

{offwork-0.1.3 → offwork-0.1.4}/offwork/worker/remote.py

@@ -280,6 +280,8 @@ async def submit_recurring(
     _root_token: bytes | None = None,
     _interval: float = 0,
     _start_at: float | None = None,
+    _run_for: float | None = None,
+    _max_runs: int | None = None,
     **kwargs: Any,
 ) -> ScheduleHandle:
     """Submit a recurring task and return a :class:`ScheduleHandle`."""
@@ -302,6 +304,7 @@ async def submit_recurring(
 
     schedule_id = uuid.uuid4().hex[:12]
     scheduled_at = _start_at or time.time()
+    recur_deadline = scheduled_at + _run_for if _run_for is not None else None
 
     opts = getattr(wrapper, "__offwork_options__", {})
     task = Task(
@@ -315,6 +318,8 @@ async def submit_recurring(
         throttle=opts.get("throttle"),
         scheduled_at=scheduled_at,
         recur_interval=_interval,
+        recur_deadline=recur_deadline,
+        recur_remaining=_max_runs,
         schedule_id=schedule_id,
     )
 
@@ -342,7 +347,7 @@ def _build_detail_tags(worker: Worker) -> str:
     return ", ".join(parts)
 
 
-_HEARTBEAT_INTERVAL = 1.0
+_HEARTBEAT_INTERVAL = 5.0
 
 
 async def _heartbeat_loop(
@@ -353,23 +358,23 @@ async def _heartbeat_loop(
 ) -> None:
     """Send periodic heartbeats and check for cancellation.
 
-    When *exec_task* is provided and the backend reports the task as
-    cancelled, the execution task is cancelled via
+    Backends override ``heartbeat_and_check_cancel`` to combine both
+    into a single round-trip (e.g. an HTTP POST whose response carries
+    the cancel flag). When *exec_task* is provided and the backend
+    reports the task as cancelled, the execution task is cancelled via
     :meth:`asyncio.Task.cancel`, which raises :class:`CancelledError`
     at the next ``await`` in async user functions.
     """
     while not cancel_event.is_set():
         try:
-            await backend.send_heartbeat(task_id)
-        except Exception:
-            logger.debug("Heartbeat send failed for task %s", task_id, exc_info=True)
-        if exec_task is not None:
-            try:
-                if await backend.is_cancelled(task_id):
+            if exec_task is not None:
+                if await backend.heartbeat_and_check_cancel(task_id):
                     exec_task.cancel()
                     return
-            except Exception:
-                logger.debug("Cancellation check failed for task %s", task_id, exc_info=True)
+            else:
+                await backend.send_heartbeat(task_id)
+        except Exception:
+            logger.debug("Heartbeat send failed for task %s", task_id, exc_info=True)
         try:
             await asyncio.wait_for(cancel_event.wait(), timeout=_HEARTBEAT_INTERVAL)
         except asyncio.TimeoutError:
@@ -634,7 +639,18 @@ async def _handle_task(
 
     # Re-enqueue recurring task — worker re-signs with its own identity.
     if task.recur_interval is not None and task.schedule_id is not None:
-        if not await backend.is_schedule_cancelled(task.schedule_id):
+        next_at = time.time() + task.recur_interval
+        remaining = task.recur_remaining
+        deadline_exceeded = task.recur_deadline is not None and next_at > task.recur_deadline
+        runs_exhausted = remaining is not None and remaining <= 1
+        if deadline_exceeded or runs_exhausted:
+            await backend.cancel_schedule(task.schedule_id)
+            logger.info(
+                "Recurring schedule %s exhausted (%s)",
+                task.schedule_id,
+                "deadline" if deadline_exceeded else "max_runs",
+            )
+        elif not await backend.is_schedule_cancelled(task.schedule_id):
             next_task = Task(
                 graph_json=task.graph_json,
                 function_name=task.function_name,
@@ -644,8 +660,10 @@ async def _handle_task(
                 retries=task.retries,
                 retry_delay=task.retry_delay,
                 throttle=task.throttle,
-                scheduled_at=time.time() + task.recur_interval,
+                scheduled_at=next_at,
                 recur_interval=task.recur_interval,
+                recur_deadline=task.recur_deadline,
+                recur_remaining=remaining - 1 if remaining is not None else None,
                 schedule_id=task.schedule_id,
             )
             await backend.submit(_encode_task(next_task, root_token))

{offwork-0.1.3 → offwork-0.1.4}/offwork/worker/result.py

@@ -134,7 +134,7 @@ class Result:
     async def result(
         self,
         timeout: float | None = None,
-        stall_timeout: float | None = 10.0,
+        stall_timeout: float | None = 600.0,
     ) -> Any:
         """Await the result.
 
@@ -171,13 +171,29 @@ class Result:
         timeout: float | None,
         stall_timeout: float,
     ) -> None:
-        """Poll for result with heartbeat-based stall detection."""
+        """Wait for the result with heartbeat-based stall detection.
+
+        Uses the backend's blocking ``get_result`` (long-poll on HTTP
+        backends) in bounded slices, with a heartbeat check between
+        slices. The slice length is derived from ``stall_timeout`` so
+        we still detect a silent worker in time.
+        """
         deadline = None if timeout is None else time.monotonic() + timeout
+        slice_seconds = max(1.0, min(stall_timeout / 2, 30.0))
         last_hb_value: float | None = None
         last_hb_change: float | None = None
 
         while True:
-            raw = await self._backend.try_get_result(self._task_id)
+            remaining = None if deadline is None else deadline - time.monotonic()
+            if remaining is not None and remaining <= 0:
+                raise TimeoutError(
+                    f"Timed out waiting for result of task {self._task_id}"
+                )
+            wait_for = slice_seconds if remaining is None else min(slice_seconds, remaining)
+            try:
+                raw = await self._backend.get_result(self._task_id, timeout=wait_for)
+            except TimeoutError:
+                raw = None
             if raw is not None:
                 self._envelope = ResultEnvelope.from_json(raw)
                 logger.debug(
@@ -186,14 +202,6 @@ class Result:
                 )
                 return
 
-            if deadline is not None:
-                remaining = deadline - time.monotonic()
-                if remaining <= 0:
-                    raise TimeoutError(
-                        f"Timed out waiting for result of task {self._task_id}"
-                    )
-
-            logger.debug("Polling heartbeat for task %s", self._task_id[:8])
             hb = await self._backend.get_heartbeat(self._task_id)
             now = time.monotonic()
             if hb is not None and hb != last_hb_value:
@@ -206,30 +214,58 @@ class Result:
                     f"{elapsed:.1f}s (threshold: {stall_timeout}s)"
                 )
 
-            await asyncio.sleep(1.0)
-
     def __await__(self) -> Generator[Any, None, Any]:
         """Allow ``await result`` as shorthand for ``await result.result()``."""
         return self.result().__await__()
 
     # -- cancellation ----------------------------------------------------------
 
-    async def cancel(self) -> None:
+    async def cancel(self, wait: bool | float = False) -> bool:
         """Cancel the task.
 
-        Marks the task as cancelled in the backend.  If the worker
-        hasn't started execution yet, it will skip the task.  If
-        execution is already in progress, it will continue but the
-        client will receive a :class:`TaskCancelled` error.
+        Marks the task as cancelled in the backend.  The worker
+        observes the flag via its heartbeat loop and aborts execution
+        cooperatively.
 
-        Awaiting the result after cancellation raises
-        :class:`TaskCancelled`.
+        Parameters
+        ----------
+        wait
+            If ``False`` (default), return immediately after signalling
+            cancellation. If ``True``, block until the worker confirms
+            (default 30s timeout). If a number, wait that many seconds
+            for confirmation.
+
+        Returns
+        -------
+        bool
+            ``True`` if cancellation was confirmed by the worker (or
+            ``wait=False``).  ``False`` if the wait timed out.
         """
         await self._backend.cancel_task(self._task_id)
-        await self._backend.send_result(
-            self._task_id,
-            ResultEnvelope.cancelled(self._task_id).to_json(),
-        )
+        if wait is False:
+            # Pre-seed a cancelled envelope so a client that never awaits
+            # confirmation still gets TaskCancelled when it reads.
+            await self._backend.send_result(
+                self._task_id,
+                ResultEnvelope.cancelled(self._task_id).to_json(),
+            )
+            return True
+        timeout = 30.0 if wait is True else float(wait)
+        deadline = time.monotonic() + timeout
+        while True:
+            raw = await self._backend.try_get_result(self._task_id)
+            if raw is not None:
+                self._envelope = ResultEnvelope.from_json(raw)
+                return True
+            if time.monotonic() >= deadline:
+                # Fall back: seed a cancelled envelope so subsequent reads
+                # don't hang forever, and tell the caller we timed out.
+                await self._backend.send_result(
+                    self._task_id,
+                    ResultEnvelope.cancelled(self._task_id).to_json(),
+                )
+                return False
+            await asyncio.sleep(0.5)
 
     # -- progress --------------------------------------------------------------
 

offwork-0.1.4/offwork/worker/schedule.py

@@ -0,0 +1,53 @@
+"""Schedule handle for recurring task management."""
+
+import asyncio
+import time
+
+from offwork.worker.backends.base import Backend
+
+
+class ScheduleHandle:
+    """Handle for a recurring schedule, allowing cancellation."""
+
+    def __init__(self, schedule_id: str, backend: Backend) -> None:
+        self._schedule_id = schedule_id
+        self._backend = backend
+
+    @property
+    def schedule_id(self) -> str:
+        return self._schedule_id
+
+    async def cancel(self, wait: bool | float = False) -> bool:
+        """Cancel this recurring schedule.
+
+        The worker stops re-enqueuing new occurrences after the
+        current one completes.
+
+        Parameters
+        ----------
+        wait
+            If ``False`` (default), return immediately. If ``True``,
+            block until the backend confirms the schedule is marked
+            cancelled (default 30s timeout). If a number, wait that
+            many seconds.
+
+        Returns
+        -------
+        bool
+            ``True`` if cancellation was acknowledged (or
+            ``wait=False``). ``False`` on timeout.
+        """
+        await self._backend.cancel_schedule(self._schedule_id)
+        if wait is False:
+            return True
+        timeout = 30.0 if wait is True else float(wait)
+        deadline = time.monotonic() + timeout
+        while True:
+            if await self._backend.is_schedule_cancelled(self._schedule_id):
+                return True
+            if time.monotonic() >= deadline:
+                return False
+            await asyncio.sleep(0.5)
+
+    def __repr__(self) -> str:
+        return f"ScheduleHandle(schedule_id={self._schedule_id!r})"

{offwork-0.1.3 → offwork-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "offwork"
-version = "0.1.3"
+version = "0.1.4"
 description = "Distributed Python task execution via automatic function serialization"
 readme = "README.md"
 authors = [

offwork-0.1.3/offwork/worker/schedule.py

@@ -1,26 +0,0 @@
-"""Schedule handle for recurring task management."""
-
-from offwork.worker.backends.base import Backend
-
-
-class ScheduleHandle:
-    """Handle for a recurring schedule, allowing cancellation."""
-
-    def __init__(self, schedule_id: str, backend: Backend) -> None:
-        self._schedule_id = schedule_id
-        self._backend = backend
-
-    @property
-    def schedule_id(self) -> str:
-        return self._schedule_id
-
-    async def cancel(self) -> None:
-        """Cancel this recurring schedule.
-
-        The worker will stop re-enqueuing new occurrences after the
-        current one completes.
-        """
-        await self._backend.cancel_schedule(self._schedule_id)
-
-    def __repr__(self) -> str:
-        return f"ScheduleHandle(schedule_id={self._schedule_id!r})"