GitHub

PersistedQueueStoreService

API reference for PersistedQueueStoreService.

The elements of every queue: make_store_memory, make_store_sql and make_store_redis build one, and PersistedQueueStoreService(offer=..., take=..., cleanup=...) makes one of three functions (a test double, say). An offer that takes no deduplicate treats every offer as "untilRemoved".

Functions

__init__

__init__(*, offer, take, cleanup) -> None
ParameterTypeDescription
offerOffer | DeduplicatingOffer
takeCallable[[TakeOptions], Effect[TakenElement, PersistedQueueError, Scope]]
cleanupCleanup
def __init__(
    self,
    *,
    offer: Offer | DeduplicatingOffer,
    take: Callable[[TakeOptions], Effect[TakenElement, PersistedQueueError, Scope]],
    cleanup: Cleanup,
) -> None:
    self._offer = offer
    # Effect's stores ignore an option they don't know; an ``offer``
    # written before ``deduplicate`` existed is called without it.
    self._offer_deduplicates = _takes_deduplicate(offer)
    self._take = take
    self._cleanup = cleanup

offer

offer(*, name, id, element, is_custom_id, delay=None, deduplicate='untilRemoved') -> Effect[None, PersistedQueueError]

Stores element (a JSON value) under id in queue name, unless the queue already has that id (is_custom_id says the caller chose it, so a store must check) and, with deduplicate "untilExecuted", that id's element has not yet completed or failed its final attempt. A delay is finite and positive: the element is not taken before it elapses. Fails with PersistedQueueError when the backend does.

ParameterTypeDescription
namestr
idstr
elementobject
is_custom_idbool
delayDuration | None = None
deduplicateDeduplicate = 'untilRemoved'

Returns Effect[None, PersistedQueueError]

def offer(
    self,
    *,
    name: str,
    id: str,
    element: object,
    is_custom_id: bool,
    delay: Duration | None = None,
    deduplicate: Deduplicate = "untilRemoved",
) -> Effect[None, PersistedQueueError]:
    """Stores ``element`` (a JSON value) under ``id`` in queue ``name``,
    unless the queue already has that id (``is_custom_id`` says the
    caller chose it, so a store must check) and, with ``deduplicate``
    ``"untilExecuted"``, that id's element has not yet completed or
    failed its final attempt. A ``delay`` is finite and positive: the
    element is not taken before it elapses. Fails with
    ``PersistedQueueError`` when the backend does."""
    if self._offer_deduplicates and deduplicate != "untilRemoved":
        offer = cast("DeduplicatingOffer", self._offer)
        return offer(
            name=name,
            id=id,
            element=element,
            is_custom_id=is_custom_id,
            delay=delay,
            deduplicate=deduplicate,
        )
    return self._offer(
        name=name, id=id, element=element, is_custom_id=is_custom_id, delay=delay
    )

take

take(options) -> Effect[TakenElement, PersistedQueueError, Scope]

Claims the next visible element of queue options.name, counting an attempt, and waits while there is none. When the scope closes, a success marks it completed, an interruption releases it without the attempt, a failure is_dead_letter_cause accepts marks it failed at once, and any other failure retries it after options.retry_delay or, on attempt options.max_attempts, marks it failed. Fails with PersistedQueueError when the backend does.

ParameterTypeDescription
optionsTakeOptions

Returns Effect[TakenElement, PersistedQueueError, Scope]

def take(self, options: TakeOptions) -> Effect[TakenElement, PersistedQueueError, Scope]:
    """Claims the next visible element of queue ``options.name``,
    counting an attempt, and waits while there is none. When the scope
    closes, a success marks it completed, an interruption releases it
    without the attempt, a failure ``is_dead_letter_cause`` accepts marks
    it failed at once, and any other failure retries it after
    ``options.retry_delay`` or, on attempt ``options.max_attempts``,
    marks it failed. Fails with
    ``PersistedQueueError`` when the backend does."""
    return self._take(options)

cleanup

cleanup(*, time_to_live, failed_time_to_live) -> Effect[None, PersistedQueueError]

Removes completed elements older than time_to_live with their de-duplication records; failed ones only when failed_time_to_live is given, once older than it. Fails with PersistedQueueError when the backend does.

ParameterTypeDescription
time_to_liveDuration
failed_time_to_liveDuration | None

Returns Effect[None, PersistedQueueError]

def cleanup(
    self, *, time_to_live: Duration, failed_time_to_live: Duration | None
) -> Effect[None, PersistedQueueError]:
    """Removes completed elements older than ``time_to_live`` with
    their de-duplication records; failed ones only when
    ``failed_time_to_live`` is given, once older than it. Fails with
    ``PersistedQueueError`` when the backend does."""
    return self._cleanup(time_to_live=time_to_live, failed_time_to_live=failed_time_to_live)