Metadata-Version: 2.4
Name: kv-cache
Version: 0.1.0
Summary: A fast key-value store using SQLite for CLI tools
Project-URL: Homepage, https://github.com/yourusername/fast-kv
Project-URL: Repository, https://github.com/yourusername/fast-kv.git
Project-URL: Documentation, https://github.com/yourusername/fast-kv#readme
Project-URL: Bug Tracker, https://github.com/yourusername/fast-kv/issues
Author-email: Your Name <your.email@example.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cache,cli,key-value,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Provides-Extra: dev
Requires-Dist: black>=22.0; extra == 'dev'
Requires-Dist: isort>=5.0; extra == 'dev'
Requires-Dist: mypy>=0.981; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest-cov>=3.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# Fast-KV

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
- 📦 Simple API
- 🛡️ Type hints included

## Installation

```bash
pip install fast-kv
```

## Quick Start

```python
from fast_kv import KeyValueStore

# Initialize the store
store = KeyValueStore("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:

```python
from fast_kv import KeyValueStore

def get_autocomplete_suggestions(prefix: str) -> list:
    store = KeyValueStore("~/.mycli/cache.db")
    
    # Try cache first
    cache_key = f"auto:{prefix}"
    results = store.get(cache_key)
    
    if results is None:
        # Cache miss - fetch from remote
        results = fetch_from_remote_server(prefix)  # Slow remote call
        store.set(cache_key, results, ttl=3600)  # Cache for 1 hour
    
    return results
```

## API Reference

### KeyValueStore

```python
class KeyValueStore:
    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."""
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/fast-kv.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

```bash
pytest tests/
```

### Code Style

The project uses `black` for code formatting and `isort` for import sorting:

```bash
# Format code
black src/ tests/

# Sort imports
isort src/ tests/
```

## License

MIT License - see LICENSE file for details.