relinker 0.6.0__py3-none-any.whl

relinker/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with development dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Check formatting
+        run: ruff format --check .
+
+      - name: Run lint
+        run: ruff check .
+
+      - name: Run type checks
+        run: mypy src
+
+      - name: Run tests
+        run: pytest

relinker/__init__.py

@@ -0,0 +1,70 @@
+"""
+Relinker public API.
+
+This module exposes the stable imports users should rely on. Internal modules can
+change, but these names should remain stable whenever possible.
+"""
+
+from __future__ import annotations
+
+from relinker.context import AsyncRetryAttemptContext, RetryAttemptContext
+from relinker.diagnostics import (
+    PolicyHealthReport,
+    PolicyWarning,
+    RetrySimulation,
+    RetrySimulationAttempt,
+)
+from relinker.exceptions import (
+    InvalidRetryConfigError,
+    RelinkerError,
+    RetryExhaustedError,
+    TryAgain,
+)
+from relinker.http import (
+    DEFAULT_RETRYABLE_STATUSES,
+    http_retry_policy,
+    parse_retry_after,
+    retry_after_delay,
+    retry_if_status,
+    should_retry_http_status,
+)
+from relinker.policy import RetryPolicy
+from relinker.presets import background_job, database, fast, network, patient
+from relinker.result import RetryResult
+from relinker.retry import retry
+from relinker.state import RetryState
+from relinker.stats import RetryStats, RetryStatsSnapshot
+from relinker.typing import RetryWrappedFunction
+
+__all__ = [
+    "AsyncRetryAttemptContext",
+    "DEFAULT_RETRYABLE_STATUSES",
+    "InvalidRetryConfigError",
+    "PolicyHealthReport",
+    "PolicyWarning",
+    "RetryAttemptContext",
+    "RetryExhaustedError",
+    "RelinkerError",
+    "RetryPolicy",
+    "RetryResult",
+    "RetrySimulation",
+    "RetrySimulationAttempt",
+    "RetryState",
+    "RetryStats",
+    "RetryStatsSnapshot",
+    "RetryWrappedFunction",
+    "TryAgain",
+    "background_job",
+    "database",
+    "fast",
+    "http_retry_policy",
+    "network",
+    "parse_retry_after",
+    "patient",
+    "retry",
+    "retry_after_delay",
+    "retry_if_status",
+    "should_retry_http_status",
+]
+
+__version__ = "0.6.0"

relinker/attempt.py

@@ -0,0 +1,46 @@
+"""
+Attempt records.
+
+An attempt is one execution of the wrapped function. Relinker stores attempts
+so users can inspect what happened after a run.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class AttemptRecord:
+    """
+    Immutable information about a single attempt.
+
+    Attributes:
+        number: One-based attempt number.
+        started_at: Monotonic timestamp when the attempt started.
+        ended_at: Monotonic timestamp when the attempt ended.
+        value: Returned value, when the attempt succeeded.
+        error: Raised exception, when the attempt failed.
+    """
+
+    number: int
+    started_at: float
+    ended_at: float
+    value: Any = None
+    error: BaseException | None = None
+
+    @property
+    def duration(self) -> float:
+        """Return how many seconds this attempt took."""
+        return self.ended_at - self.started_at
+
+    @property
+    def succeeded(self) -> bool:
+        """Return True when this attempt completed without an exception."""
+        return self.error is None
+
+    @property
+    def failed(self) -> bool:
+        """Return True when this attempt raised an exception."""
+        return self.error is not None

relinker/conditions/__init__.py

@@ -0,0 +1,17 @@
+"""Retry conditions."""
+
+from relinker.conditions.base import ConditionMixin, RetryCondition
+from relinker.conditions.composite import AllCondition, AnyCondition
+from relinker.conditions.custom import CustomCondition
+from relinker.conditions.exception import ExceptionCondition
+from relinker.conditions.result import ResultCondition
+
+__all__ = [
+    "AllCondition",
+    "AnyCondition",
+    "ConditionMixin",
+    "CustomCondition",
+    "ExceptionCondition",
+    "ResultCondition",
+    "RetryCondition",
+]

relinker/conditions/base.py

@@ -0,0 +1,41 @@
+"""Base retry condition interfaces and composition helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, cast
+
+
+class RetryCondition(Protocol):
+    """
+    Protocol implemented by retry conditions.
+
+    A condition can decide based on an exception, a returned value, or both.
+    """
+
+    def should_retry_exception(self, error: BaseException) -> bool:
+        """Return True when this exception should be retried."""
+
+    def should_retry_result(self, value: Any) -> bool:
+        """Return True when this returned value should be retried."""
+
+
+class ConditionMixin:
+    """
+    Mixin that gives retry conditions boolean composition.
+
+    This mixin is intentionally not a Protocol itself. The cast calls below tell
+    static type checkers that classes using this mixin are expected to implement
+    the RetryCondition protocol.
+    """
+
+    def __or__(self, other: RetryCondition) -> RetryCondition:
+        """Return a condition that passes when either condition passes."""
+        from relinker.conditions.composite import AnyCondition
+
+        return AnyCondition((cast(RetryCondition, self), other))
+
+    def __and__(self, other: RetryCondition) -> RetryCondition:
+        """Return a condition that passes only when both conditions pass."""
+        from relinker.conditions.composite import AllCondition
+
+        return AllCondition((cast(RetryCondition, self), other))

relinker/conditions/composite.py

@@ -0,0 +1,38 @@
+"""Composite retry conditions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from relinker.conditions.base import ConditionMixin, RetryCondition
+
+
+@dataclass(frozen=True, slots=True)
+class AnyCondition(ConditionMixin):
+    """Retries when any child condition says retry."""
+
+    conditions: tuple[RetryCondition, ...]
+
+    def should_retry_exception(self, error: BaseException) -> bool:
+        """Return True when any child retries this exception."""
+        return any(condition.should_retry_exception(error) for condition in self.conditions)
+
+    def should_retry_result(self, value: Any) -> bool:
+        """Return True when any child retries this value."""
+        return any(condition.should_retry_result(value) for condition in self.conditions)
+
+
+@dataclass(frozen=True, slots=True)
+class AllCondition(ConditionMixin):
+    """Retries only when all child conditions say retry."""
+
+    conditions: tuple[RetryCondition, ...]
+
+    def should_retry_exception(self, error: BaseException) -> bool:
+        """Return True when all children retry this exception."""
+        return all(condition.should_retry_exception(error) for condition in self.conditions)
+
+    def should_retry_result(self, value: Any) -> bool:
+        """Return True when all children retry this value."""
+        return all(condition.should_retry_result(value) for condition in self.conditions)

relinker/conditions/custom.py

@@ -0,0 +1,29 @@
+"""Custom retry condition."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from relinker.conditions.base import ConditionMixin
+
+
+@dataclass(frozen=True, slots=True)
+class CustomCondition(ConditionMixin):
+    """
+    Fully custom retry condition.
+
+    The callback receives either an error or a value. Exactly one of them will
+    be non-None for each decision.
+    """
+
+    callback: Callable[[BaseException | None, Any], bool]
+
+    def should_retry_exception(self, error: BaseException) -> bool:
+        """Return True when the callback says the exception should be retried."""
+        return bool(self.callback(error, None))
+
+    def should_retry_result(self, value: Any) -> bool:
+        """Return True when the callback says the value should be retried."""
+        return bool(self.callback(None, value))

relinker/conditions/exception.py

@@ -0,0 +1,26 @@
+"""Retry condition based on exception types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from relinker.conditions.base import ConditionMixin
+from relinker.internal.validation import ensure_exception_types
+
+
+@dataclass(frozen=True, slots=True)
+class ExceptionCondition(ConditionMixin):
+    """Retries when the raised exception matches one of the configured types."""
+
+    exception_types: tuple[type[BaseException], ...] = (Exception,)
+
+    def __post_init__(self) -> None:
+        ensure_exception_types(self.exception_types)
+
+    def should_retry_exception(self, error: BaseException) -> bool:
+        """Return True when the error matches the configured exception types."""
+        return isinstance(error, self.exception_types)
+
+    def should_retry_result(self, value: object) -> bool:
+        """Exception-based conditions do not retry successful return values."""
+        return False

relinker/conditions/result.py

@@ -0,0 +1,24 @@
+"""Retry condition based on returned values."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from relinker.conditions.base import ConditionMixin
+
+
+@dataclass(frozen=True, slots=True)
+class ResultCondition(ConditionMixin):
+    """Retries when a user-provided predicate returns True for a value."""
+
+    predicate: Callable[[Any], bool]
+
+    def should_retry_exception(self, error: BaseException) -> bool:
+        """Result-based conditions do not retry exceptions."""
+        return False
+
+    def should_retry_result(self, value: Any) -> bool:
+        """Return True when the value should trigger another attempt."""
+        return bool(self.predicate(value))