Skip to main content

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kv_cache-0.3.0.tar.gz (15.7 kB view details)

Uploaded Source

Built Distribution

kv_cache-0.3.0-py3-none-any.whl (9.4 kB view details)

Uploaded Python 3

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

Hashes for kv_cache-0.3.0.tar.gz
Algorithm Hash digest
SHA256 d6c0c13d613036210733ce885196d0b4a028bb683c12253d645af88f917d72c7
MD5 072012cbdb3f35a049a6e9b8edaf5543
BLAKE2b-256 182c0871de73844351f2da7b006a46f0c69682d429ed40cf1c2d2778f34e5cd7

See more details on using hashes here.

Provenance

The following attestation bundles were made for kv_cache-0.3.0.tar.gz:

Publisher: publish-pypi.yml on lcances/kv_cache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

Hashes for kv_cache-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5711d6b5091cdedffd61b2f9d6ee4d4bb78357cd2181386c9891fa5874353fd6
MD5 810861a50f20fcb181fb82074a08322b
BLAKE2b-256 7646104f69d2fb7da49c46818e264427539b7f163a06c353408f92ff6ebba043

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page