Stores¶

Stores are implementations of the AsyncKeyValue protocol that provide actual storage backends.

Memory Store¶

In-memory key-value store, useful for testing and development.

MemoryStore ¶

Bases: BaseDestroyStore, BaseDestroyCollectionStore, BaseEnumerateCollectionsStore, BaseEnumerateKeysStore

A fixed-size in-memory key-value store using TLRU (Time-aware Least Recently Used) cache.

init ¶

__init__(
    *, max_entries_per_collection=None, default_collection=None, seed=None
)

Initialize a fixed-size in-memory store.

Parameters:

Name	Type	Description	Default
`max_entries_per_collection`	`int \| None`	The maximum number of entries per collection. Defaults to no limit.	`None`
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`
`seed`	`SEED_DATA_TYPE \| None`	Optional seed data to pre-populate the store. Format: {collection: {key: {field: value, ...}}}. Each value must be a mapping (dict) that will be stored as the entry's value. Seeding occurs lazily when each collection is first accessed.	`None`

Disk Store¶

Persistent disk-based key-value store using DiskCache.

DiskStore ¶

Bases: BaseContextManagerStore, BaseStore

A disk-based store that uses the diskcache library to store data.

init ¶

__init__(*, disk_cache: Cache, default_collection: str | None = None) -> None

__init__(
    *,
    directory: Path | str,
    max_size: int | None = None,
    default_collection: str | None = None,
) -> None

__init__(
    *, disk_cache=None, directory=None, max_size=None, default_collection=None
)

Initialize the disk store.

Parameters:

Name	Type	Description	Default
`disk_cache`	`Cache \| None`	An existing diskcache Cache instance to use. If provided, the store will not manage the cache's lifecycle (will not close it). The caller is responsible for managing the cache's lifecycle.	`None`
`directory`	`Path \| str \| None`	The directory to use for the disk store.	`None`
`max_size`	`int \| None`	The maximum size of the disk store.	`None`
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`

FileTree Store¶

Directory-based store for visual inspection and testing.

FileTreeStore ¶

Bases: BaseStore

A file-tree based store using directories for collections and files for keys.

This store uses the native filesystem: - Each collection is a subdirectory under the base directory - Each key is stored as a JSON file named "{key}.json" - File contents contain the ManagedEntry serialized to JSON

Directory structure

{base_directory}/ {collection_1}/ {key_1}.json {key_2}.json {collection_2}/ {key_3}.json

By default, collections and keys are not sanitized. This means that filesystem limitations on path lengths and special characters may cause errors when trying to get and put entries.

To avoid issues, you may want to consider leveraging the FileTreeV1CollectionSanitizationStrategy and FileTreeV1KeySanitizationStrategy strategies.

Warning

This store is intended for development and testing purposes only. It is not suitable for production use due to: - Poor performance with many keys - No atomic operations - No built-in cleanup of expired entries - Filesystem limitations on file names and directory sizes

The store does NOT automatically clean up expired entries from disk. Expired entries are only filtered out when read via get() or similar methods.

init ¶

__init__(
    *,
    data_directory,
    metadata_directory=None,
    default_collection=None,
    serialization_adapter=None,
    key_sanitization_strategy=None,
    collection_sanitization_strategy=None,
)

Initialize the file-tree store.

Parameters:

Name	Type	Description	Default
`data_directory`	`Path \| str`	The base directory to use for storing collections and keys.	required
`metadata_directory`	`Path \| str \| None`	The directory to use for storing metadata. Defaults to data_directory.	`None`
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`
`serialization_adapter`	`SerializationAdapter \| None`	The serialization adapter to use for the store.	`None`
`key_sanitization_strategy`	`SanitizationStrategy \| None`	The sanitization strategy to use for keys.	`None`
`collection_sanitization_strategy`	`SanitizationStrategy \| None`	The sanitization strategy to use for collections.	`None`

Redis Store¶

Redis-backed key-value store.

RedisStore ¶

Bases: BaseDestroyStore, BaseEnumerateKeysStore, BaseContextManagerStore, BaseStore

Redis-based key-value store.

init ¶

__init__(*, client: Redis, default_collection: str | None = None) -> None

__init__(*, url: str, default_collection: str | None = None) -> None

__init__(
    *,
    host: str = "localhost",
    port: int = 6379,
    db: int = 0,
    password: str | None = None,
    default_collection: str | None = None,
) -> None

__init__(
    *,
    client=None,
    default_collection=None,
    url=None,
    host="localhost",
    port=6379,
    db=0,
    password=None,
)

Initialize the Redis store.

Parameters:

Name	Type	Description	Default
`client`	`Redis \| None`	An existing Redis client to use. If provided, the store will not manage the client's lifecycle (will not close it). The caller is responsible for managing the client's lifecycle.	`None`
`url`	`str \| None`	Redis URL (e.g., redis://localhost:6379/0).	`None`
`host`	`str`	Redis host. Defaults to localhost.	`'localhost'`
`port`	`int`	Redis port. Defaults to 6379.	`6379`
`db`	`int`	Redis database number. Defaults to 0.	`0`
`password`	`str \| None`	Redis password. Defaults to None.	`None`
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`

DynamoDB Store¶

AWS DynamoDB-backed key-value store.

DynamoDBStore ¶

Bases: BaseContextManagerStore, BaseStore

DynamoDB-based key-value store.

This store uses a single DynamoDB table with a composite primary key: - collection (partition key) - key (sort key)

init ¶

__init__(
    *,
    client: AioBaseClient,
    table_name: str,
    default_collection: str | None = None,
) -> None

__init__(
    *,
    table_name: str,
    region_name: str | None = None,
    endpoint_url: str | None = None,
    aws_access_key_id: str | None = None,
    aws_secret_access_key: str | None = None,
    aws_session_token: str | None = None,
    default_collection: str | None = None,
) -> None

__init__(
    *,
    client=None,
    table_name,
    region_name=None,
    endpoint_url=None,
    aws_access_key_id=None,
    aws_secret_access_key=None,
    aws_session_token=None,
    default_collection=None,
)

Initialize the DynamoDB store.

Parameters:

Name	Type	Description	Default
`client`	`AioBaseClient \| None`	The DynamoDB client to use. If provided, the store will not manage the client's lifecycle (will not enter/exit its context manager). The caller is responsible for managing the client's lifecycle and must ensure the client is already entered.	`None`
`table_name`	`str`	The name of the DynamoDB table to use.	required
`region_name`	`str \| None`	AWS region name. Defaults to None (uses AWS default).	`None`
`endpoint_url`	`str \| None`	Custom endpoint URL (useful for local DynamoDB). Defaults to None.	`None`
`aws_access_key_id`	`str \| None`	AWS access key ID. Defaults to None (uses AWS default credentials).	`None`
`aws_secret_access_key`	`str \| None`	AWS secret access key. Defaults to None (uses AWS default credentials).	`None`
`aws_session_token`	`str \| None`	AWS session token. Defaults to None (uses AWS default credentials).	`None`
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`

Elasticsearch Store¶

Elasticsearch-backed key-value store.

ElasticsearchStore ¶

Bases: BaseEnumerateCollectionsStore, BaseEnumerateKeysStore, BaseDestroyCollectionStore, BaseCullStore, BaseContextManagerStore, BaseStore

An Elasticsearch-based store.

Stores collections in their own indices and stores values in Flattened fields.

This store has specific restrictions on what is allowed in keys and collections. Keys and collections are not sanitized by default which may result in errors when using the store.

To avoid issues, you may want to consider leveraging the ElasticsearchV1KeySanitizationStrategy and ElasticsearchV1CollectionSanitizationStrategy strategies.

init ¶

__init__(
    *,
    elasticsearch_client: AsyncElasticsearch,
    index_prefix: str,
    default_collection: str | None = None,
    key_sanitization_strategy: SanitizationStrategy | None = None,
    collection_sanitization_strategy: SanitizationStrategy | None = None,
) -> None

__init__(
    *,
    url: str,
    api_key: str | None = None,
    index_prefix: str,
    default_collection: str | None = None,
    key_sanitization_strategy: SanitizationStrategy | None = None,
    collection_sanitization_strategy: SanitizationStrategy | None = None,
) -> None

__init__(
    *,
    elasticsearch_client=None,
    url=None,
    api_key=None,
    index_prefix,
    default_collection=None,
    key_sanitization_strategy=None,
    collection_sanitization_strategy=None,
)

Initialize the elasticsearch store.

Parameters:

Name	Type	Description	Default
`elasticsearch_client`	`AsyncElasticsearch \| None`	The elasticsearch client to use. If provided, the store will not manage the client's lifecycle (will not close it). The caller is responsible for managing the client's lifecycle.	`None`
`url`	`str \| None`	The url of the elasticsearch cluster.	`None`
`api_key`	`str \| None`	The api key to use.	`None`
`index_prefix`	`str`	The index prefix to use. Collections will be prefixed with this prefix.	required
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`
`key_sanitization_strategy`	`SanitizationStrategy \| None`	The sanitization strategy to use for keys.	`None`
`collection_sanitization_strategy`	`SanitizationStrategy \| None`	The sanitization strategy to use for collections.	`None`

MongoDB Store¶

MongoDB-backed key-value store.

MongoDBStore ¶

Bases: BaseDestroyCollectionStore, BaseContextManagerStore, BaseStore

MongoDB-based key-value store using pymongo.

Stores collections as MongoDB collections and stores values in document fields.

By default, collections are not sanitized. This means that there are character and length restrictions on collection names that may cause errors when trying to get and put entries.

To avoid issues, you may want to consider leveraging the MongoDBV1CollectionSanitizationStrategy strategy.

init ¶

__init__(
    *,
    client: AsyncMongoClient[dict[str, Any]],
    db_name: str | None = None,
    coll_name: str | None = None,
    default_collection: str | None = None,
    collection_sanitization_strategy: SanitizationStrategy | None = None,
) -> None

__init__(
    *,
    url: str,
    db_name: str | None = None,
    coll_name: str | None = None,
    default_collection: str | None = None,
    collection_sanitization_strategy: SanitizationStrategy | None = None,
) -> None

__init__(
    *,
    client=None,
    url=None,
    db_name=None,
    coll_name=None,
    default_collection=None,
    collection_sanitization_strategy=None,
)

Initialize the MongoDB store.

Values are stored as native BSON dictionaries for better query support and performance.

Parameters:

Name	Type	Description	Default
`client`	`AsyncMongoClient[dict[str, Any]] \| None`	The MongoDB client to use (mutually exclusive with url). If provided, the store will not manage the client's lifecycle (will not enter/exit its context manager or close it). The caller is responsible for managing the client's lifecycle.	`None`
`url`	`str \| None`	The url of the MongoDB cluster (mutually exclusive with client).	`None`
`db_name`	`str \| None`	The name of the MongoDB database.	`None`
`coll_name`	`str \| None`	The name of the MongoDB collection.	`None`
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`
`collection_sanitization_strategy`	`SanitizationStrategy \| None`	The sanitization strategy to use for collections.	`None`

Valkey Store¶

Valkey-backed key-value store (Redis-compatible).

ValkeyStore ¶

Bases: BaseContextManagerStore, BaseStore

Valkey-based key-value store (Redis protocol compatible).

init ¶

__init__(*, client: BaseClient, default_collection: str | None = None) -> None

__init__(
    *,
    host: str = "localhost",
    port: int = 6379,
    db: int = 0,
    username: str | None = None,
    password: str | None = None,
    default_collection: str | None = None,
) -> None

__init__(
    *,
    client=None,
    default_collection=None,
    host="localhost",
    port=6379,
    db=0,
    username=None,
    password=None,
)

Initialize the Valkey store.

Parameters:

Name	Type	Description	Default
`client`	`BaseClient \| None`	An existing Valkey client to use. If provided, the store will not manage the client's lifecycle (will not close it). The caller is responsible for managing the client's lifecycle.	`None`
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`
`host`	`str`	Valkey host. Defaults to localhost.	`'localhost'`
`port`	`int`	Valkey port. Defaults to 6379.	`6379`
`db`	`int`	Valkey database number. Defaults to 0.	`0`
`username`	`str \| None`	Valkey username. Defaults to None.	`None`
`password`	`str \| None`	Valkey password. Defaults to None.	`None`

Memcached Store¶

Memcached-backed key-value store.

MemcachedStore ¶

Bases: BaseDestroyStore, BaseContextManagerStore, BaseStore

Memcached-based key-value store using aiomcache.

By default, keys are not sanitized. This means that there are character and length restrictions on keys that may cause errors when trying to get and put entries.

To avoid issues, you may want to consider leveraging the MemcachedV1KeySanitizationStrategy strategy.

init ¶

__init__(
    *,
    client: Client,
    default_collection: str | None = None,
    key_sanitization_strategy: SanitizationStrategy | None = None,
) -> None

__init__(
    *,
    host: str = "127.0.0.1",
    port: int = 11211,
    default_collection: str | None = None,
    key_sanitization_strategy: SanitizationStrategy | None = None,
) -> None

__init__(
    *,
    client=None,
    host="127.0.0.1",
    port=11211,
    default_collection=None,
    key_sanitization_strategy=None,
)

Initialize the Memcached store.

Parameters:

Name	Type	Description	Default
`client`	`Client \| None`	An existing aiomcache client to use. If provided, the store will not manage the client's lifecycle (will not close it). The caller is responsible for managing the client's lifecycle.	`None`
`host`	`str`	Memcached host. Defaults to 127.0.0.1.	`'127.0.0.1'`
`port`	`int`	Memcached port. Defaults to 11211.	`11211`
`default_collection`	`str \| None`	The default collection to use if no collection is provided.	`None`
`key_sanitization_strategy`	`SanitizationStrategy \| None`	The sanitization strategy to use for keys.	`None`

Null Store¶

A no-op store that doesn't persist anything, useful for testing.

NullStore ¶

Bases: BaseStore

Null object pattern store that accepts all operations but stores nothing.

Stores¶

Memory Store¶

MemoryStore ¶

__init__ ¶

Disk Store¶

DiskStore ¶

__init__ ¶

FileTree Store¶

FileTreeStore ¶

__init__ ¶

Redis Store¶

RedisStore ¶

__init__ ¶

DynamoDB Store¶

DynamoDBStore ¶

__init__ ¶

Elasticsearch Store¶

ElasticsearchStore ¶

__init__ ¶

MongoDB Store¶

MongoDBStore ¶

__init__ ¶

Valkey Store¶

ValkeyStore ¶

__init__ ¶

Memcached Store¶

MemcachedStore ¶

__init__ ¶

Null Store¶

NullStore ¶

init ¶

init ¶

init ¶

init ¶

init ¶

init ¶

init ¶

init ¶

init ¶