A fast key-value store using SQLite for CLI tools
Project description
KV_Cache
A fast key-value store using SQLite as a backend, designed specifically for CLI tools needing persistent cache storage.
Features
- 🚀 Fast SQLite-based storage
- ⏰ Built-in TTL support
- 🔒 Thread-safe operations
- 🧹 Automatic cleanup of expired entries
Installation
pip install kv-cache
Quick Start
from kv_cache import KVStore
# Initialize the store
store = KVStore("cache.db")
# Store a value with 1-hour TTL
store.set("my_key", {"data": "value"}, ttl=3600)
# Retrieve the value
value = store.get("my_key")
print(value) # {'data': 'value'}
# Delete when done
store.delete("my_key")
Usage with CLI Autocomplete
Perfect for caching slow remote calls in CLI tools:
import time
from kv_cache import KVStore, scache
# directly use the store
def get_autocomplete_suggestions(prefix: str) -> list:
store = KVStore("~/.mycli/store.db")
# Try cache first
store_key = f"auto:{prefix}"
results = store.get(store_key)
if results is None:
# Cache miss - fetch from remote
results = fetch_from_remote_server(prefix) # Slow remote call
store.set(store_key, results, ttl=3600) # Cache for 1 hour
return results
# or use the `scache` decorator to easily cache the function result
@scache(ttl=3600, KVStore("~/.mycli/store.db"))
def long_function_call(arg1, arg2, arg3=None):
time.sleep(1)
long_function_call(1, 2, arg3='test') # will take 1 seconds
long_function_call(1, 2, arg3='test') # instant
API Reference
KVStore
class KVStore:
def __init__(self, db_path: str, table_name: str = "key_value_store"):
"""Initialize the store with database path and optional table name."""
def set(self, key: str, value: Any, ttl: Optional[int] = None):
"""Set a value with optional TTL in seconds."""
def get(self, key: str, default: Any = None) -> Any:
"""Get a value or return default if not found."""
def delete(self, key: str):
"""Delete a key from the store."""
def clear(self):
"""Clear all entries from the store."""
def close(self):
"""Close the database connection."""
def __enter__(self):
def __exit__(self):
""" Context manager to use with `with` """
Development
Setup
# Clone the repository
git clone https://github.com/lcances/kv_cache.git
cd fast-kv
# Create virtual environment
python -m venv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows
# Install development dependencies
pip install -e ".[dev]"
Running Tests
pytest tests/
Code Style
The project uses black
for code formatting and isort
for import sorting:
# Format code
black src/ tests/
# Sort imports
isort src/ tests/
License
MIT License - see LICENSE file for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file kv_cache-0.3.0.tar.gz
.
File metadata
- Download URL: kv_cache-0.3.0.tar.gz
- Upload date:
- Size: 15.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
d6c0c13d613036210733ce885196d0b4a028bb683c12253d645af88f917d72c7
|
|
MD5 |
072012cbdb3f35a049a6e9b8edaf5543
|
|
BLAKE2b-256 |
182c0871de73844351f2da7b006a46f0c69682d429ed40cf1c2d2778f34e5cd7
|
Provenance
The following attestation bundles were made for kv_cache-0.3.0.tar.gz
:
Publisher:
publish-pypi.yml
on lcances/kv_cache
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1
-
Predicate type:
https://docs.pypi.org/attestations/publish/v1
-
Subject name:
kv_cache-0.3.0.tar.gz
-
Subject digest:
d6c0c13d613036210733ce885196d0b4a028bb683c12253d645af88f917d72c7
- Sigstore transparency entry: 242884925
- Sigstore integration time:
-
Permalink:
lcances/kv_cache@dd35e22d0655b074db2b1a1b87b0da39e1f5ad09
-
Branch / Tag:
refs/tags/0.3.0
- Owner: https://github.com/lcances
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com
-
Runner Environment:
github-hosted
-
Publication workflow:
publish-pypi.yml@dd35e22d0655b074db2b1a1b87b0da39e1f5ad09
-
Trigger Event:
release
-
Statement type:
File details
Details for the file kv_cache-0.3.0-py3-none-any.whl
.
File metadata
- Download URL: kv_cache-0.3.0-py3-none-any.whl
- Upload date:
- Size: 9.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
5711d6b5091cdedffd61b2f9d6ee4d4bb78357cd2181386c9891fa5874353fd6
|
|
MD5 |
810861a50f20fcb181fb82074a08322b
|
|
BLAKE2b-256 |
7646104f69d2fb7da49c46818e264427539b7f163a06c353408f92ff6ebba043
|
Provenance
The following attestation bundles were made for kv_cache-0.3.0-py3-none-any.whl
:
Publisher:
publish-pypi.yml
on lcances/kv_cache
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1
-
Predicate type:
https://docs.pypi.org/attestations/publish/v1
-
Subject name:
kv_cache-0.3.0-py3-none-any.whl
-
Subject digest:
5711d6b5091cdedffd61b2f9d6ee4d4bb78357cd2181386c9891fa5874353fd6
- Sigstore transparency entry: 242884926
- Sigstore integration time:
-
Permalink:
lcances/kv_cache@dd35e22d0655b074db2b1a1b87b0da39e1f5ad09
-
Branch / Tag:
refs/tags/0.3.0
- Owner: https://github.com/lcances
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com
-
Runner Environment:
github-hosted
-
Publication workflow:
publish-pypi.yml@dd35e22d0655b074db2b1a1b87b0da39e1f5ad09
-
Trigger Event:
release
-
Statement type: