wallet_helper.remote module

RemoteLedger: use a wallet-helper HTTP server as a shared, remote store.

A LedgerLike backend that talks to the dedup server in wallet_helper.api. Point a wallet at one and every process, on any host, shares the same store and the same in-flight lease, so the same heavy call is not run twice across a whole fleet:

>>> from wallet_helper import Wallet, memoize
>>> from wallet_helper.remote import RemoteLedger
>>> wallet = Wallet(RemoteLedger("http://cache.internal:8000"))
>>> @memoize(wallet=wallet)
... def transcribe(path):
...     return call_some_paid_api(path)

Because it offers claim / submit / release, Wallet routes through the server’s lease, giving cross-process single-flight with no extra code.

It uses only the Python standard library (urllib), so a client host needs nothing installed beyond wallet-helper itself. The HTTP call is isolated in RemoteLedger._request(), which can be replaced with a custom transport (handy in tests).

Author

Warith HARCHAOUI, https://linkedin.com/in/warith-harchaoui

class wallet_helper.remote.RemoteLedger(base_url, *, timeout=30.0, request=None)[source]

Bases: object

A ledger backed by a wallet-helper HTTP server.

Parameters:

  • base_url (str) – Root URL of the server, for example "http://127.0.0.1:8000". A trailing slash is fine; it is trimmed.

  • timeout (float, optional) – Per-request timeout in seconds. Defaults to 30.

  • request (callable, optional) – A custom transport request(method, path, body) -> dict | None used instead of the built-in urllib one. Mainly for tests, where it can route to a FastAPI TestClient.

claim(key, lease_seconds=300.0)[source]

Get the cached result, or lease the right to compute it (see the server).

Parameters:
Return type:

dict

clear(namespace=None)[source]

Delete results on the server, all of them or just one namespace.

Parameters:

namespace (str | None)

Return type:

None

evict(*, max_entries=None, older_than=None)[source]

Prune results on the server and return how many were removed.

Parameters:

  • max_entries (int | None)

  • older_than (float | None)

Return type:

int

extend(key, token=None)[source]

Renew a lease on the server for a long-running job.

Parameters:

  • key (str)

  • token (str | None)

Return type:

bool

get(key)[source]

Return just the stored result for key, or None if absent.

Parameters:

key (str)

Return type:

Any | None

get_record(key)[source]

Return a partial record {"key", "result"} for key, or None.

Parameters:

key (str)

Return type:

dict | None

has(key)[source]

Return True if the server has a result stored for key.

Parameters:

key (str)

Return type:

bool

property location: str

The server URL that backs this ledger (for display).

put(key, result, *, ttl=None)[source]

Store result for key on the server (an alias for submit).

Parameters:
Return type:

None

register_hit(key)[source]

No-op: the server counts reuses itself, on claim hits and result reads.

Parameters:

key (str)

Return type:

None

release(key, token=None)[source]

Drop a lease on the server so a waiter can take over (your own, if fenced).

Parameters:

  • key (str)

  • token (str | None)

Return type:

None

stats(namespace=None)[source]

Return {entries, hits} from the server (namespace filter optional).

Parameters:

namespace (str | None)

Return type:

dict

submit(key, result, *, token=None, ttl=None)[source]

Store a leader’s result on the server and release its own lease.

Parameters:
Return type:

dict