persista 0.0.2a0

library for persisting and caching data

persista

Overview

persista is a lightweight Python library that provides simple, consistent building blocks for persisting and caching data. It offers a uniform key-value store interface backed by multiple storage engines (in-memory, SQLite, DuckDB, LMDB, Redis, PostgreSQL) with both sync and async APIs, plus TTL caching and HTTP fetch utilities.

Quick Links:

• Documentation
• Installation
• Features
• Contributing
• License

Why persista?

Storage backends have different APIs, and switching between them (e.g. moving from an in-memory store in tests to Redis or PostgreSQL in production) usually means rewriting code. persista solves this with a single, consistent BaseStore interface:

Store and retrieve values:

>>> from persista.store import InMemoryStore
>>> store = InMemoryStore()
>>> store.set("user:1", {"name": "Alice"})
>>> store.get("user:1")
{'name': 'Alice'}

Swap the backend without changing the calling code:

>>> import tempfile
>>> from pathlib import Path
>>> from persista.store import SQLiteStore
>>> with tempfile.TemporaryDirectory() as tmpdir:
...     with SQLiteStore(Path(tmpdir).joinpath("data.sqlite")) as store:
...         store.set("user:1", {"name": "Alice"})
...         store.get("user:1")
...
{'name': 'Alice'}

Cache expensive calls with a TTL:

>>> from persista.cache import cached
>>> @cached(ttl=60)
... def slow_call(x: int) -> int:
...     return x**2
...
>>> slow_call(4)
16

See the documentation for detailed examples.

Features

persista provides a comprehensive set of utilities for persisting and caching data:

🗄️ Key-Value Stores

A consistent BaseStore / AsyncBaseStore interface for storing dict values under string keys:

• Uniform API across backends: get, get_many, set, set_many, delete, filter, iteration
• Sync backends: InMemoryStore, SQLiteStore, DuckDBStore, LmdbStore, RedisStore, PostgresStore
• Async backends: AsyncInMemoryStore, AsyncSQLiteStore, AsyncRedisStore, AsyncPostgresStore
• Typed variants (TypedSQLiteStore, TypedPostgresStore, ...) and pickle-backed variants (PickleLmdbStore, PickleRedisStore, AsyncPickleRedisStore) for non-dict values
• Configurable conflict handling on writes ("raise", "skip", "overwrite")

⏱️ TTL Caching

Time-to-live caching for functions and values, with sync and async variants:

• TTLCache and AsyncTTLCache for explicit cache instances
• cached / async_cached decorators for caching function calls
• Shared default caches via get_ttl_cache / get_async_ttl_cache

🌐 HTTP Utilities

Helpers to fetch HTTP responses with automatic retries, built on top of requests or httpx:

• fetch_response (sync, requests) and fetch_response_async (async, httpx)

Installation

We highly recommend installing persista in a virtual environment to avoid dependency conflicts.

Using uv (recommended)

uv is a fast Python package installer and resolver:

uv pip install persista

Install with specific optional dependencies:

uv pip install persista[redis,httpx]  # with Redis and httpx support

Using pip

Alternatively, you can use pip:

pip install persista

Install with specific optional dependencies:

pip install persista[redis,httpx]  # with Redis and httpx support

Requirements

• Python: 3.10 or higher
• Core dependencies: coola

Optional dependencies, enabled per-backend:

Extra	Enables
aiosqlite	Async SQLite store
duckdb	DuckDB store
faker	Test data generation helpers
httpx	Async HTTP fetch utilities
lmdb	LMDB store
psycopg	PostgreSQL store
redis	Redis store
requests	Sync HTTP fetch utilities
rich	Rich-formatted output
urllib3	urllib3-based HTTP utilities

For detailed installation instructions, see the documentation.

Contributing

Contributions are welcome! We appreciate bug fixes, feature additions, documentation improvements, and more. Please check the contributing guidelines for details on:

• Setting up the development environment
• Code style and testing requirements
• Submitting pull requests

Whether you're fixing a bug or proposing a new feature, please open an issue first to discuss your changes.

API Stability

:warning: Important: As persista is under active development, its API is not yet stable and may change between releases. We recommend pinning a specific version in your project’s dependencies to ensure consistent behavior.

License

persista is licensed under BSD 3-Clause "New" or "Revised" license available in LICENSE file.