sidejob 0.1.0__py3-none-any.whl

sidejob/__init__.py

@@ -0,0 +1,71 @@
+"""sidejob: simple, observable, fail-loud background jobs for data workflows.
+
+Quick start::
+
+    import sidejob
+
+    manager = sidejob.initialize(max_workers=4)
+    with manager.workflow() as run:
+        run.parallel_job(upload_to_redshift, df, "analytics_table")
+        summary = analyze(df)
+        run.wait_all()          # MANDATORY: raises if a required job failed
+    write_success_marker()      # reached only on full success
+"""
+
+from ._status import JobStatus
+from .context import (
+    JobContext,
+    cancel_requested,
+    check_cancelled,
+    current_job,
+    on_cancel,
+    sleep,
+)
+from .errors import (
+    JobCancelledError,
+    JobsFailedError,
+    ManagerShutdownError,
+    SidejobError,
+    TransientError,
+    UnknownJobError,
+    WaitAllNotCalledError,
+    WaitTimeoutError,
+    WorkflowClosedError,
+)
+from .manager import Job, JobManager, initialize
+from .records import AttemptRecord, JobEvent, JobRun, WaitReport
+from .retry import DEFAULT_NEVER_RETRY, DEFAULT_RETRYABLE, RetryPolicy
+from .workflow import Workflow
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_NEVER_RETRY",
+    "DEFAULT_RETRYABLE",
+    "AttemptRecord",
+    "Job",
+    "JobCancelledError",
+    "JobContext",
+    "JobEvent",
+    "JobManager",
+    "JobRun",
+    "JobStatus",
+    "JobsFailedError",
+    "ManagerShutdownError",
+    "RetryPolicy",
+    "SidejobError",
+    "TransientError",
+    "UnknownJobError",
+    "WaitAllNotCalledError",
+    "WaitReport",
+    "WaitTimeoutError",
+    "Workflow",
+    "WorkflowClosedError",
+    "__version__",
+    "cancel_requested",
+    "check_cancelled",
+    "current_job",
+    "initialize",
+    "on_cancel",
+    "sleep",
+]

sidejob/_status.py

@@ -0,0 +1,37 @@
+"""Job status enumeration."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class JobStatus(str, Enum):
+    """Lifecycle state of a background job.
+
+    ``QUEUED``     Submitted, waiting for a free worker.
+    ``RUNNING``    An attempt is currently executing.
+    ``RETRYING``   An attempt failed with a retryable error; waiting out the backoff
+                   delay before the next attempt.
+    ``COMPLETED``  The submitted function returned normally (terminal).
+    ``FAILED``     The final attempt raised, or the error was not retryable (terminal).
+    ``CANCELLED``  Cancelled before an attempt started (terminal).
+    """
+
+    QUEUED = "QUEUED"
+    RUNNING = "RUNNING"
+    RETRYING = "RETRYING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+
+    @property
+    def is_terminal(self) -> bool:
+        """True for ``COMPLETED``, ``FAILED`` and ``CANCELLED``."""
+        return self in _TERMINAL
+
+    def __str__(self) -> str:
+        return self.value
+
+
+_TERMINAL = frozenset({JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED})
+TERMINAL_STATUSES = _TERMINAL

sidejob/context.py

@@ -0,0 +1,177 @@
+"""Cooperative cancellation and per-attempt context for code running inside a job.
+
+Python threads cannot be killed safely, so stopping running work requires the
+job's cooperation. These helpers make that easy and are **no-ops outside a
+job**, so the same function also works when called directly::
+
+    import sidejob
+
+    def export_partitions(df, partitions):
+        for p in partitions:
+            sidejob.check_cancelled()      # raises JobCancelledError if cancel() was requested
+            write_partition(df, p)
+
+    def poll_until_ready(client, query_id):
+        while not client.is_done(query_id):
+            sidejob.sleep(5)               # wakes up immediately on cancellation
+
+    def upload(df, table):
+        conn = connect()
+        sidejob.on_cancel(conn.cancel)     # abort the in-flight query on cancel()
+        ...
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from .errors import JobCancelledError
+
+if TYPE_CHECKING:
+    from .manager import JobManager, _JobRecord
+
+__all__ = [
+    "JobContext",
+    "cancel_requested",
+    "check_cancelled",
+    "current_job",
+    "on_cancel",
+    "sleep",
+]
+
+_state = threading.local()
+
+
+class JobContext:
+    """Information about the job attempt running on the current thread.
+
+    Obtain it with :func:`sidejob.current_job` inside a job function.
+
+    Attributes:
+        job_id: The job's ID.
+        name: The job's display name.
+        attempt: The current attempt number (1 = first attempt).
+        max_attempts: The configured attempt budget.
+        workflow_id: The workflow the job belongs to, if any.
+    """
+
+    __slots__ = ("_manager", "_rec", "attempt", "job_id", "max_attempts", "name", "workflow_id")
+
+    def __init__(self, manager: JobManager, rec: _JobRecord, attempt: int) -> None:
+        self._manager = manager
+        self._rec = rec
+        self.job_id: str = rec.job_id
+        self.name: str = rec.name
+        self.attempt = attempt
+        self.max_attempts: int = rec.policy.max_attempts
+        self.workflow_id: Optional[str] = rec.workflow_id
+
+    @property
+    def is_retry(self) -> bool:
+        """True from the second attempt on.
+
+        Check it before repeating a side effect: an earlier attempt may have
+        committed its write before the error reached your code.
+        """
+        return self.attempt > 1
+
+    @property
+    def idempotency_key(self) -> str:
+        """A key that stays the same across all attempts of this job.
+
+        Store it with the data you write (or use it as a deduplication key) so a
+        retry can detect that an earlier attempt already succeeded. It is the
+        job ID, which is unique per submission; for a key that survives process
+        restarts, pass your own (for example ``f"{table}:{run_date}"``).
+        """
+        return self.job_id
+
+    @property
+    def cancel_requested(self) -> bool:
+        """True once cancellation of this job has been requested."""
+        return self._rec.cancel_event.is_set()
+
+    def check_cancelled(self) -> None:
+        """Raise :class:`JobCancelledError` if cancellation was requested."""
+        if self._rec.cancel_event.is_set():
+            raise JobCancelledError(self.job_id)
+
+    def sleep(self, seconds: float) -> None:
+        """Sleep, but wake up and raise :class:`JobCancelledError` on cancellation."""
+        if seconds < 0:
+            raise ValueError("sleep length must be non-negative")
+        if self._rec.cancel_event.wait(seconds):
+            raise JobCancelledError(self.job_id)
+
+    def on_cancel(self, callback: Callable[[], Any]) -> None:
+        """Register ``callback()`` to run when cancellation is requested.
+
+        Use it to abort blocking work from the outside, for example
+        ``conn.cancel`` (psycopg2/psycopg, many DB-API drivers) or
+        ``lambda: spark.sparkContext.cancelJobGroup(group)``.
+
+        * Callbacks run on the thread that requested cancellation (or on the
+          scheduler thread for ``cancel_on_deadline``), not on the job's thread.
+        * They apply to the current attempt only and are discarded when it ends.
+        * If cancellation was already requested, ``callback`` runs immediately.
+        * Exceptions raised by a callback are logged, never propagated.
+        * A callback may race with the attempt finishing, so it must be safe to
+          call on an already-closed resource.
+        """
+        self._manager._register_cancel_callback(self._rec, self.attempt, callback)
+
+    def __repr__(self) -> str:
+        return (
+            f"JobContext(job_id={self.job_id!r}, name={self.name!r}, "
+            f"attempt={self.attempt}/{self.max_attempts})"
+        )
+
+
+def current_job() -> Optional[JobContext]:
+    """The :class:`JobContext` of the job running on this thread, or ``None``.
+
+    The context is thread-local: threads that a job starts itself do not see
+    it. Pass the context object to them explicitly if needed.
+    """
+    ctx: Optional[JobContext] = getattr(_state, "context", None)
+    return ctx
+
+
+def cancel_requested() -> bool:
+    """True if the current job has a pending cancellation request (False outside jobs)."""
+    ctx = current_job()
+    return ctx is not None and ctx.cancel_requested
+
+
+def check_cancelled() -> None:
+    """Raise :class:`JobCancelledError` if the current job should stop (no-op outside jobs)."""
+    ctx = current_job()
+    if ctx is not None:
+        ctx.check_cancelled()
+
+
+def sleep(seconds: float) -> None:
+    """Cancellation-aware ``time.sleep`` (plain ``time.sleep`` outside jobs)."""
+    ctx = current_job()
+    if ctx is None:
+        time.sleep(seconds)
+    else:
+        ctx.sleep(seconds)
+
+
+def on_cancel(callback: Callable[[], Any]) -> None:
+    """Register a cancellation hook for the current attempt (no-op outside jobs).
+
+    See :meth:`JobContext.on_cancel`.
+    """
+    ctx = current_job()
+    if ctx is not None:
+        ctx.on_cancel(callback)
+
+
+def _set_context(ctx: Optional[JobContext]) -> Optional[JobContext]:
+    prev: Optional[JobContext] = getattr(_state, "context", None)
+    _state.context = ctx
+    return prev

sidejob/errors.py

@@ -0,0 +1,114 @@
+"""Exception types raised by sidejob."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+
+if TYPE_CHECKING:
+    from .records import JobRun, WaitReport
+
+
+class SidejobError(Exception):
+    """Base class for all sidejob errors."""
+
+
+class TransientError(SidejobError):
+    """Raise (or subclass) inside a job to mark a failure as retryable.
+
+    It is part of the default retryable set, so wrapping a driver error is an
+    easy way to opt into retries::
+
+        try:
+            cursor.execute(sql)
+        except redshift_connector.InterfaceError as exc:
+            raise sidejob.TransientError("connection dropped") from exc
+    """
+
+
+class UnknownJobError(SidejobError, LookupError):
+    """The job ID (or handle) does not belong to this manager."""
+
+    def __init__(self, job_id: str, hint: str = "") -> None:
+        super().__init__(f"Unknown job id: {job_id!r}{hint}")
+        self.job_id = job_id
+
+
+class ManagerShutdownError(SidejobError, RuntimeError):
+    """A job was submitted to a manager that has been shut down."""
+
+
+class WorkflowClosedError(SidejobError, RuntimeError):
+    """A job was submitted to a workflow that is not open (not entered or already exited)."""
+
+
+class JobCancelledError(SidejobError):
+    """The job was cancelled.
+
+    Raised by ``get_result()`` for a CANCELLED job, and inside a job by
+    :func:`sidejob.check_cancelled` / :func:`sidejob.sleep` once cancellation
+    has been requested.
+    """
+
+    def __init__(self, job_id: str) -> None:
+        super().__init__(f"Job {job_id} was cancelled before it ran to completion")
+        self.job_id = job_id
+
+
+class WaitTimeoutError(SidejobError, TimeoutError):
+    """Waiting for job(s) exceeded the allowed time.
+
+    A wait timeout is *not* a job failure: the jobs listed in ``pending`` are
+    still queued, running or retrying, and their status is left untouched.
+    A timeout never means success.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        pending: Sequence[JobRun] = (),
+        failures: Sequence[JobRun] = (),
+    ) -> None:
+        super().__init__(message)
+        self.pending: Tuple[JobRun, ...] = tuple(pending)
+        self.failures: Tuple[JobRun, ...] = tuple(failures)
+
+    @property
+    def pending_job_ids(self) -> Tuple[str, ...]:
+        return tuple(r.job_id for r in self.pending)
+
+
+class JobsFailedError(SidejobError):
+    """One or more *required* jobs failed or were cancelled.
+
+    Attributes:
+        failures: Snapshots of the required jobs that did not complete.
+        job_ids: Their IDs.
+        exceptions: The original final exception of each FAILED job.
+        report: The full :class:`~sidejob.WaitReport` (all selected jobs).
+    """
+
+    def __init__(self, failures: Sequence[JobRun], report: Optional[WaitReport] = None) -> None:
+        self.failures: Tuple[JobRun, ...] = tuple(failures)
+        self.report = report
+        super().__init__(self._build_message())
+
+    @property
+    def job_ids(self) -> Tuple[str, ...]:
+        return tuple(r.job_id for r in self.failures)
+
+    @property
+    def exceptions(self) -> Tuple[BaseException, ...]:
+        return tuple(r.exception for r in self.failures if r.exception is not None)
+
+    def _build_message(self) -> str:
+        lines = [f"{len(self.failures)} required job(s) did not complete successfully:"]
+        lines.extend(f"  - {r.describe()}" for r in self.failures)
+        return "\n".join(lines)
+
+
+class WaitAllNotCalledError(SidejobError):
+    """A strict workflow exited without a successful explicit ``wait_all()``.
+
+    The jobs were still waited for and checked; this error exists so that a
+    forgotten safety barrier is caught instead of silently tolerated.
+    """