Flag-Aware Cache Adapter

Build a cache adapter that customizes encoding and decoding rules for a memcached-backed client, registering its hooks so cache operations honor custom flags and treating unknown flags as misses.

Capabilities

JSON payload encoding

• Setting a dictionary stores it as UTF-8 JSON with a custom flag value, and reading it returns the same dictionary structure. @test

Raw bytes passthrough

• Setting a bytes value stores it unchanged with a neutral flag so reading yields identical bytes. @test

Unknown flags act as misses

• When the backend returns data with an unrecognized flag, read operations return the default value without raising and without altering the cache. @test

Implementation

@generates

API

class FlagAwareCacheAdapter:
    def __init__(self, backend, json_flag: int = 0x99, raw_flag: int = 0):
        ...

    def set(self, key: str, value, ttl: int = 0) -> bool:
        """Store a value with optional TTL using the backend."""

    def get(self, key: str, default=None):
        """Fetch a value, returning default when treating data as a miss."""

    def serialize(self, value) -> tuple[bytes, int]:
        """Encode a value and return (payload, flag) pair for backend storage."""

    def deserialize(self, data: bytes, flag: int):
        """Decode backend payloads, treating unsupported flags as cache misses."""

Dependencies { .dependencies }

pylibmc { .dependency }

Memcached client that allows overriding serialization hooks and using cache-miss sentinels.