aiokv/README.md

aiokv

Async file-backed key-value store for single-process local state — last-used command, rate-limit timestamps, seen-IDs, simple bot state. Persists forever to a JSON file with atomic writes.

It is a KV store, not a cache: no TTL, no expiry, no eviction. Values live until you delete or clear them.

Install

requirements.txt:

aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v1.1.0

Direct:

pip install "aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v1.1.0"

Requires aiofiles (pulled transitively).

Drop the @v1.1.0 suffix from the line above to install the latest unpinned.

Usage

from aiokv import AioKV

kv = AioKV("state.json")

await kv.set("last_command", "ping")
await kv.set("seen_ran_cleanup")             # value omitted -> stores int(time.time())

cmd  = await kv.get("last_command")          # "ping"
when = await kv.get("seen_ran_cleanup")      # the unix timestamp
miss = await kv.get("absent", default=0)     # 0

await kv.delete("last_command")              # True (removed or absent)
everything = await kv.get_all()              # {"seen_ran_cleanup": ...}
await kv.clear()                             # removes the file

The timestamp default (set(key) with no value) is for "mark that I saw/did X at time T" — the common rate-limit / seen-ID pattern.

Back-compat

This lib was originally aiocache. Legacy call sites keep working — aiocache is a re-export alias of AioKV:

from aiokv import aiocache      # alias of AioKV; same API
kv = aiocache("state.json")

Prefer AioKV in new code.

Memory model

The file is read once, on first use, and then served from memory: get / get_all don't touch the disk, and each set / delete writes the whole store back atomically. get and get_all return deep copies, and set stores the value's JSON round-trip (exactly what a reload would give back), so mutating a value you passed in or got back never changes the store. Because it is single-process, an edit to the file made by something else after the first read is not seen (and is overwritten by the next write). Orphaned temp files are swept once per instance, on its first save.

Durability

Writes are atomic: data is written to a temp file in the same directory and os.replace()d over the target's realpath — symlink-safe, so a symlinked store file is written through rather than clobbered. A process crash mid-write leaves the previous good file intact, and a reader never observes a partial file. (This is process-crash safety, not power-loss durability — there's no fsync, so an OS/power failure could still lose the last write; fine for reconstructible single-process state.) clear() is symlink-safe the same way: it removes the realpath'd target, not the symlink itself, so a symlinked store is genuinely erased rather than just having its symlink unlinked. Orphaned .<pid>.tmp files left by a hard crash of a different, dead process are swept on the next save; the sweep matches only the exact <realpath basename>.<pid>.tmp shape it creates, so a differently-shaped neighbor file is never touched and a store filename containing glob-like characters (e.g. state[prod].json) doesn't miss its own orphans or cross-match another store's. A single asyncio.Lock guards every read and write, so concurrent operations on one instance are consistent and no update is lost. All blocking filesystem calls and JSON (de)serialization run via asyncio.to_thread, so nothing stalls the event loop.

Scope — read this

• Single-process, single-instance only. The lock is per-instance. Two AioKV instances — or two processes — pointing at the same file are not safe; they will clobber each other's writes. For shared cross-process / cross-bot state, that is a database's job (e.g. our mongo lib), not aiokv.
• Not a cache. No TTL/expiry/eviction. If you need entries that age out, this is the wrong tool.

Error contract

• Keys must be str — get / set raise ValueError on a non-str key (JSON object keys are always strings, so a non-str key would silently never round-trip).
• get / set / get_all raise on unexpected I/O. _load raises JSONDecodeError on a truncated/corrupt file, and ValueError when the file holds valid JSON that isn't an object (a bare list/number/string/null) — so corruption or a wrong-shaped file is visible rather than silently masked. Non-finite floats (NaN/Infinity) raise ValueError on set rather than persisting invalid JSON.
• delete / clear log the exception and return False on error, True otherwise.

Versioning

Releases are tagged vX.Y.Z. The install line above pins a release; drop the @vX.Y.Z suffix to install the latest unpinned. Pin deliberately for reproducible installs.