cache_dynamo_based#

Note

TTL and automatic DynamoDB cleanup

When ttl is set, an expired entry is deleted from DynamoDB at the moment it is first read back after expiry, no DynamoDB native TTL configuration or background job is required to keep the table clean.

Because TTLs are typically set to hours or days, expirations are infrequent; the extra DeleteItem call on each expiry has negligible overhead compared to the cost of recomputing the cached value.

DynamoDB-backed caching decorator.

class core_aws.decorators.cache_dynamo_based._DynamoBackend(fcn_qualname: str, table: str, ttl: float | None = None, dynamo_kwargs: Dict[str, Any] | None = None)[source]#

Bases: L2Backend

L2Backend that stores cache entries as pickled Binary attributes in a DynamoDB table. Each entry is stored under the partition key {qualname}/{md5_of_cache_key} and uses the following attribute schema:

  • cache_key (S): partition key containing the namespaced hash.

  • v (B): pickled value.

  • t (N): Unix timestamp of creation (used for TTL checks).

When ttl is set, an expired entry is deleted from DynamoDB at the moment it is first read back after expiry — no DynamoDB TTL configuration or background job is required to keep the table clean.

Because TTLs are typically set to hours or days, expirations are infrequent; the extra DeleteItem call on each expiry has negligible overhead compared to the cost of recomputing the cached value.

The DynamoDB client is created lazily on the first cache access, and a threading.Lock ensures the initialization is thread-safe.

Required table schema (user must pre-create)

Partition key : cache_key  (String)
Attribute     : v          (Binary): pickled value
Attribute     : t          (Number): Unix creation timestamp
__init__(fcn_qualname: str, table: str, ttl: float | None = None, dynamo_kwargs: Dict[str, Any] | None = None) → None[source]#
Parameters:

  • fcn_qualname – __qualname__ of the decorated function; used to derive a unique partition-key prefix so different functions never share entries, even within the same table.

  • table – Name of the DynamoDB table where cached items are stored.

  • ttl –

    Time-to-live in seconds. Entries older than this are deleted from DynamoDB and treated as a miss on load(). None means entries never expire.

    Because TTLs are typically set to hours or days, expirations are infrequent; the extra DeleteItem call on expiry has negligible overhead and keeps the table clean automatically, without requiring DynamoDB native TTL configuration.

  • dynamo_kwargs – Extra keyword arguments forwarded to DynamoDbClient. Must include region (e.g. {"region": "us-east-1"}).

property _dynamo_client: DynamoDbClient#
_item_key(cache_key: Any) → str[source]#
load(cache_key: Any) → Any[source]#

Return the cached value, or _MISS when:

  • the DynamoDB item does not exist, or

  • the entry is older than ttl seconds, in which case the stale item is deleted from DynamoDB before returning _MISS, keeping the table clean without relying on DynamoDB native TTL configuration.

Because TTLs are typically set to hours or days, these deletions are infrequent and the extra DeleteItem call has negligible overhead.

Raises:

AwsClientException – If the GetItem call fails.

save(cache_key: Any, value: Any) → None[source]#

Persist value in DynamoDB under cache_key.

Writes cache_key (S), v (B, pickled value), and t (N, current timestamp).

Raises:

AwsClientException – If the PutItem call fails.

_abc_impl = <_abc._abc_data object>#
core_aws.decorators.cache_dynamo_based.cache_dynamo_based(*, table: str, maxsize: int | None = None, ttl: float | None = None, dynamo_kwargs: Dict[str, Any] | None = None) → Callable[source]#

Write-through caching decorator: L1 is a bounded in-memory LRU (_CacheWrapper); the fallback is a DynamoDB table (_DynamoBackend).

Every new result is written to both L1 and DynamoDB immediately. When L1 is full the least-recently-used entry is evicted from memory only; the DynamoDB item is kept. A subsequent call with the same arguments (from the same or a different process/machine) reloads the value from DynamoDB without invoking the wrapped function.

Parameters:

  • table – Name of the DynamoDB table where cached items are stored. The table must already exist and have cache_key (String) as its partition key.

  • maxsize – Maximum number of entries kept in the in-memory L1 cache. None means unbounded.

  • ttl –

    Time-to-live in seconds applied to both layers. Expired L1 entries are evicted from memory. Expired DynamoDB items are deleted from DynamoDB immediately on first read after expiry, keeping the table clean without requiring DynamoDB native TTL configuration. None (default) means entries never expire.

    TTLs are typically set to hours or days, so expirations are infrequent and the extra DeleteItem call has negligible overhead.

  • dynamo_kwargs – Extra keyword arguments forwarded to DynamoDbClient. Must include region (e.g. {"region": "us-east-1"}).

Returns:

The wrapped function.

Example

from core_aws.decorators import cache_dynamo_based

@cache_dynamo_based(
    table="my-cache-table",
    ttl=3600,
    dynamo_kwargs={"region": "us-east-1"},
)
def fetch_reference_data(dataset: str) -> dict:
    ...