docs: compress prose/module docstrings, em-dash->hyphen (de-bloat wave 1)
Signed-off-by: disqualifier <dev@disqualifier.me>
This commit is contained in:
@@ -12,18 +12,18 @@ you `delete` or `clear` them.
|
|||||||
`requirements.txt`:
|
`requirements.txt`:
|
||||||
|
|
||||||
```
|
```
|
||||||
aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v0.2.0
|
aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v0.2.1
|
||||||
```
|
```
|
||||||
|
|
||||||
Direct:
|
Direct:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install "aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v0.2.0"
|
pip install "aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v0.2.1"
|
||||||
```
|
```
|
||||||
|
|
||||||
Requires `aiofiles` (pulled transitively).
|
Requires `aiofiles` (pulled transitively).
|
||||||
|
|
||||||
Drop the `@v0.2.0` suffix from the line above to install the latest unpinned.
|
Drop the `@v0.2.1` suffix from the line above to install the latest unpinned.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|||||||
|
|
||||||
[project]
|
[project]
|
||||||
name = "aiokv"
|
name = "aiokv"
|
||||||
version = "0.2.0"
|
version = "0.2.1"
|
||||||
description = "Async file-backed key-value store for single-process local state — atomic writes, no TTL, config-free, installable."
|
description = "Async file-backed key-value store for single-process local state — atomic writes, no TTL, config-free, installable."
|
||||||
requires-python = ">=3.10"
|
requires-python = ">=3.10"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
from .aiokv import AioKV, aiocache
|
from .aiokv import AioKV, aiocache
|
||||||
|
|
||||||
__version__ = "0.2.0"
|
__version__ = "0.2.1"
|
||||||
|
|
||||||
__all__ = ["AioKV", "aiocache"]
|
__all__ = ["AioKV", "aiocache"]
|
||||||
|
|||||||
+10
-27
@@ -1,35 +1,19 @@
|
|||||||
"""
|
"""
|
||||||
async file-backed key-value store for single-process local state
|
async file-backed key-value store for single-process local state
|
||||||
|
|
||||||
a persist-forever KV store (last-used-command, rate-limit timestamps, seen-ids,
|
a persist-forever KV store backed by a JSON file, not a cache (no TTL/expiry/eviction).
|
||||||
simple bot state) backed by a JSON file. NOT a cache: no TTL, no expiry, no
|
see README for usage and the full API.
|
||||||
eviction — values live until you delete or clear them.
|
|
||||||
|
|
||||||
from aiokv import AioKV
|
from aiokv import AioKV
|
||||||
|
|
||||||
kv = AioKV("state.json")
|
kv = AioKV("state.json")
|
||||||
await kv.set("last_seen", 12345)
|
await kv.set("last_seen", 12345)
|
||||||
await kv.set("ran_cleanup") # value omitted -> stores int(time.time())
|
when = await kv.get("last_seen")
|
||||||
when = await kv.get("ran_cleanup")
|
|
||||||
await kv.delete("last_seen")
|
|
||||||
|
|
||||||
durability: atomic writes (temp file + os.replace, symlink-safe), stale
|
atomic writes are process-crash safe (temp file + os.replace) but NOT power-loss safe
|
||||||
`.<pid>.tmp` files from a hard crash are swept on save. this is process-crash
|
(no fsync). the lock is per-instance only - two AioKV instances or processes on the
|
||||||
safety, NOT power-loss durability — no fsync, so an OS/power failure can still
|
same file will clobber each other; this is single-process local state, not shared
|
||||||
lose the last write. a single asyncio.Lock guards every read and write, so
|
cross-process storage.
|
||||||
concurrent operations on one instance are consistent. JSON (de)serialization
|
|
||||||
runs off-loop via asyncio.to_thread so a large store never stalls other tasks.
|
|
||||||
|
|
||||||
scope: SINGLE-PROCESS, single-instance local state only. the lock is per-instance —
|
|
||||||
two AioKV instances (or two processes) pointing at the same file are NOT safe and
|
|
||||||
will clobber each other. for shared cross-process/cross-bot state, use a database
|
|
||||||
(e.g. mongo), not this.
|
|
||||||
|
|
||||||
config-free: the file path is passed at construction; nothing is read from a global
|
|
||||||
config. keys must be str (ValueError otherwise — JSON object keys are always
|
|
||||||
strings, so a non-str key would silently never round-trip). errors in delete/clear
|
|
||||||
are logged and swallowed (returning False); get/set raise on unexpected i/o so a
|
|
||||||
real failure is visible.
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
import os
|
import os
|
||||||
@@ -106,7 +90,7 @@ class AioKV:
|
|||||||
|
|
||||||
@staticmethod
|
@staticmethod
|
||||||
def _check_key(key: str) -> None:
|
def _check_key(key: str) -> None:
|
||||||
"""raise ValueError if key is not str (JSON object keys are always strings)"""
|
"""raise ValueError if key is not str"""
|
||||||
if not isinstance(key, str):
|
if not isinstance(key, str):
|
||||||
raise ValueError(f"aiokv keys must be str, got {type(key).__name__}")
|
raise ValueError(f"aiokv keys must be str, got {type(key).__name__}")
|
||||||
|
|
||||||
@@ -128,7 +112,7 @@ class AioKV:
|
|||||||
async def _save(self, cache: Dict[str, Any]) -> None:
|
async def _save(self, cache: Dict[str, Any]) -> None:
|
||||||
"""write atomically: temp file in the same dir, then os.replace over the realpath'd
|
"""write atomically: temp file in the same dir, then os.replace over the realpath'd
|
||||||
target (symlink-safe). process-crash safe (a crash mid-write leaves the prior good
|
target (symlink-safe). process-crash safe (a crash mid-write leaves the prior good
|
||||||
file intact), NOT power-loss safe — no fsync, so an OS/power failure can still lose
|
file intact), NOT power-loss safe - no fsync, so an OS/power failure can still lose
|
||||||
the last write (acceptable: reconstructible single-process state, not a db)"""
|
the last write (acceptable: reconstructible single-process state, not a db)"""
|
||||||
target = await asyncio.to_thread(os.path.realpath, self.file)
|
target = await asyncio.to_thread(os.path.realpath, self.file)
|
||||||
directory = os.path.dirname(target) or "."
|
directory = os.path.dirname(target) or "."
|
||||||
@@ -181,6 +165,5 @@ class AioKV:
|
|||||||
return True
|
return True
|
||||||
|
|
||||||
|
|
||||||
# back-compat: this lib was originally named aiocache; legacy call sites using
|
# back-compat: originally named aiocache; prefer AioKV in new code.
|
||||||
# `aiocache(...)` keep working via this alias. prefer AioKV in new code.
|
|
||||||
aiocache = AioKV
|
aiocache = AioKV
|
||||||
|
|||||||
Reference in New Issue
Block a user