py-key-value-aio

library0.4.5pypypi✓ verified 27d ago

py-key-value-aio is an asynchronous Python library offering a pluggable interface for various Key-Value (KV) stores. It provides a backend-agnostic abstraction layer, allowing framework authors and applications to integrate KV storage without committing to a specific implementation like Redis, DynamoDB, or an in-memory solution. The library, currently at version 0.4.4, focuses exclusively on async/await patterns and requires Python >=3.10. It is actively maintained as part of a larger monorepo.

database http-networking

pip install py-key-value-aio

package ↗

INSTALL

IMPORT

SIG · PY-KEY-VALUE-AIO

py-key-value-aio

databasepythonv0.4.5

Install

2.3s avg

Import

424ms

Disk

33MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 2.5s

py 3.11

✓ —

✓ 2.43s

py 3.12

✓ —

✓ 2.23s

py 3.13

✓ —

✓ 2.23s

py 3.9

✕ build_error

33MB installed

● package 33MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AsyncKeyValue

✓ from key_value.aio.protocols.key_value import AsyncKeyValue

MemoryStore

✓ from key_value.aio.stores.memory import MemoryStore

✗ from key_value.stores.memory import MemoryStore

Ensure you import from the 'aio' submodule for the async version of the library.

This quickstart demonstrates the core `put`, `get`, and `delete` operations using the `AsyncKeyValue` protocol and an in-memory store. It highlights the asynchronous nature of the library and the common pattern of accepting the `AsyncKeyValue` protocol in your application logic, allowing the underlying store implementation to be swapped easily.

import asyncio from key_value.aio.protocols.key_value import AsyncKeyValue from key_value.aio.stores.memory import MemoryStore async def example_usage(key_value_store: AsyncKeyValue): print(f"Putting key 'user:123' with value {{'name': 'Alice'}}") await key_value_store.put(key="user:123", value={"name": "Alice"}, collection="users", ttl=3600) print("Retrieving 'user:123'...") user_data = await key_value_store.get(key="user:123", collection="users") print(f"Retrieved: {user_data}") print("Deleting 'user:123'...") await key_value_store.delete(key="user:123", collection="users") print("Attempting to retrieve 'user:123' again...") deleted_user_data = await key_value_store.get(key="user:123", collection="users") print(f"Retrieved after deletion: {deleted_user_data}") # Should be None async def main(): # Example with MemoryStore memory_store = MemoryStore() await example_usage(memory_store) if __name__ == '__main__': asyncio.run(main())

Debug

Known issues

breakingThis library is strictly async-only. A synchronous wrapper is not planned, so ensure your application uses `async/await` patterns consistently when integrating `py-key-value-aio`.

fix

Rewrite blocking code paths to use `async/await` and integrate with an `asyncio` event loop. Do not attempt to use this library in synchronous contexts directly.

affects: All versions

gotchaValues retrieved from the store are 'managed entries' (often JSON-serialized) and are copies, not 'live' objects. Modifying the retrieved dictionary or Pydantic model will not affect the stored value until you explicitly `put` it back. The library ensures type safety but does not return the same in-memory instance.

fix

Always assume retrieved values are copies. If modifications need to be persisted, explicitly call `await key_value_store.put(key, updated_value, ...)` after modifying the local copy.

affects: All versions

gotchaThe library utilizes `beartype` for runtime type checking on core protocol methods. Violations will raise `TypeError`. This can be unexpected if not accounted for during development or if data types are inconsistent.

fix

Ensure that values passed to `put` and retrieved data conform to the expected types, especially when using Pydantic models. For debugging or specific scenarios, runtime type checks can be disabled by setting the environment variable `PY_KEY_VALUE_DISABLE_BEARTYPE=true`.

affects: All versions

gotchaWhile `py-key-value-aio` provides many backend integrations, their maturity and specific limitations may vary. Relying on certain backends in production without thorough review of their specific documentation and caveats within the `py-key-value` monorepo can lead to unexpected behavior.

fix

Always consult the official `py-key-value` GitHub monorepo documentation for details on individual backend implementations (e.g., DynamoDB, S3, Redis) before deploying them in production environments.

affects: All versions

breakingThe `py-key-value-aio` library requires Python version 3.10 or higher. Running it in environments with Python 3.9 or lower will result in installation failures due to `Requires-Python` metadata.

fix

Ensure your project's Python interpreter is version 3.10 or newer before attempting to install and use `py-key-value-aio`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'key_value_aio'

The `py-key-value-aio` package is either not installed in your Python environment or the import statement uses an incorrect top-level module name.

fix

Install the library using pip: `pip install py-key-value-aio`.

ImportError: cannot import name 'FernetEncryptionWrapper' from 'key_value.aio.wrappers.encryption'

The specific class or module path you are trying to import (`FernetEncryptionWrapper` from `key_value.aio.wrappers.encryption`) does not exist in your installed version of `py-key-value-aio`, potentially due to a version mismatch or a change in the library's structure.

fix

Ensure your `py-key-value-aio` version is compatible with the code you are using (e.g., `pip install --upgrade py-key-value-aio` to get the latest), and consult the official documentation for the correct import paths for your version.

TypeError: object 'coroutine' is not awaitable

An asynchronous function (coroutine) from `py-key-value-aio` was called without the necessary `await` keyword within an `async` function. Python's `asyncio` requires coroutines to be explicitly awaited to execute.

fix

Prepend the call to the asynchronous function with `await`. For example, change `store.get(...)` to `await store.get(...)`.

RuntimeWarning: coroutine '...' was never awaited

You have created a coroutine object by calling an `async def` function, but you did not `await` it, `yield from` it, or schedule it with `asyncio.create_task()`, meaning its execution was never started or completed.

fix

If the coroutine should run, either `await` it, `yield from` it, or schedule it as a task, e.g., `asyncio.create_task(my_coroutine())`. If it's the entry point, use `asyncio.run(my_coroutine())`.

KeyError: 'some_key'

Your application attempted to retrieve a value from the key-value store using a key that does not exist within that store or collection, or a dictionary returned by the store is missing an expected key.

fix

Before accessing a key, check for its existence (e.g., `if key in await store.keys():`) or use methods that provide a default value for missing keys (e.g., `value = await store.get(key, default=None)`), or implement a `try-except KeyError` block to handle the missing key gracefully.

Upgrade

Version history

0.4.5latest on PyPI · released May 27, 2026

Audit

Dependencies

beartyperequiredRuntime type checking and enforcement.

typing-extensionsrequiredProvides backported and experimental typing features.

anyiooptionalBackend for asynchronous operations.

diskcacheoptionalDisk-based store backend.

redisoptionalRedis store backend.

Agent activity

14 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/py-key-value-aio/ ↗