# YokedCache
High-Performance Caching for Modern Python Applications
<div align="center">
[](https://github.com/sirstig/yokedcache/stargazers)
[](https://pypi.org/project/yokedcache/)
[](https://pypi.org/project/yokedcache/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/sirstig/yokedcache/actions/workflows/test.yml)
[](https://codecov.io/gh/sirstig/yokedcache)
[](https://github.com/psf/black)
</div>
Intelligent caching with automatic invalidation, fuzzy search, and seamless FastAPI integration.
**[Documentation](https://sirstig.github.io/yokedcache)** | **[Report Bug](https://github.com/sirstig/yokedcache/issues)** | **[Request Feature](https://github.com/sirstig/yokedcache/issues)**
## Table of Contents
- [Overview](#overview)
- [Key Features](#key-features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Usage Examples](#usage-examples)
- [CLI Usage](#cli-usage)
- [Performance](#performance)
- [Architecture](#architecture)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
---
## Overview
Traditional caching solutions require manual cache management and lack intelligent invalidation. YokedCache solves this with:
- **Smart Auto-Invalidation**: Automatically detects database changes and invalidates related caches
- **Multi-Backend Support**: Redis, Memcached, and in-memory backends for flexibility
- **Zero-Code Integration**: Drop-in replacement for your existing database dependencies
- **Intelligent Tagging**: Group and invalidate related caches effortlessly
- **Advanced Search**: Traditional fuzzy search plus vector-based semantic similarity
- **Production Monitoring**: Prometheus and StatsD integration for real-time metrics
- **Professional Tooling**: Comprehensive CLI with CSV export and monitoring capabilities
## Quick Start
```bash
pip install yokedcache
```
```python
from fastapi import FastAPI, Depends
from yokedcache import cached_dependency
app = FastAPI()
# Replace your database dependency
cached_get_db = cached_dependency(get_db, ttl=300)
@app.get("/users/{user_id}")
async def get_user(user_id: int, db=Depends(cached_get_db)):
# Your existing code - no changes needed!
return db.query(User).filter(User.id == user_id).first()
```
That's it! Your database queries are now cached with automatic invalidation.
## Key Features
### 🔐 Production-Grade Resilience *(New in v0.2.1)*
- **Circuit Breaker Pattern**: Prevents cascading failures during Redis outages
- **Connection Pool Management**: Advanced Redis connection configuration
- **Retry Logic**: Exponential backoff for transient failures
- **Health Monitoring**: Comprehensive cache status and performance metrics
- **Graceful Fallbacks**: Application stability during cache issues
### 🔄 Enhanced Async/Sync Support *(New in v0.2.1)*
- **Smart Context Detection**: Prevents Task object returns in mixed environments
- **Explicit Method Variants**: `aget`/`aset` for async, `get_sync`/`set_sync` for sync
- **FastAPI Generator Support**: Better handling of database session dependencies
- **Performance Optimization**: Improved serialization and key generation
### Multi-Backend Architecture
- **Redis**: Full-featured backend with clustering and persistence support
- **Memcached**: High-performance distributed caching
- **In-Memory**: Fast local caching for development and testing
- Pluggable backend system for custom implementations
### Smart Invalidation
- Automatic cache invalidation on database writes
- Tag-based grouping for related data
- Pattern-based invalidation with wildcards
- Configurable rules per table/operation
### Advanced Search Capabilities
- Traditional fuzzy search with configurable thresholds
- Vector-based semantic similarity using TF-IDF and cosine similarity
- Multiple similarity algorithms (cosine, euclidean, manhattan)
- Redis vector persistence for large-scale deployments
### Deep Integration
- Zero-code FastAPI integration
- SQLAlchemy ORM support
- Async/await throughout
- Connection pooling & health checks
### Production Monitoring
- **Prometheus**: Native metrics export for Grafana dashboards
- **StatsD**: Real-time metrics for DataDog, Grafana, and other platforms
- Comprehensive performance tracking and alerting
- Custom metrics collection support
### Professional Tooling
- Comprehensive CLI for cache control and monitoring
- CSV export for data analysis and reporting
- Real-time statistics with watch mode
- YAML-based configuration with validation
- Cache warming and bulk operations
## Installation
```bash
# Basic installation (Redis backend only)
pip install yokedcache
# With specific features
pip install yokedcache[memcached] # Add Memcached support
pip install yokedcache[monitoring] # Add Prometheus/StatsD support
pip install yokedcache[vector] # Add vector similarity search
pip install yokedcache[fuzzy] # Add traditional fuzzy search
# Full installation with all features
pip install yokedcache[full]
# Development installation
pip install yokedcache[dev]
```
## Documentation
| Guide | Link | Description |
|-------|------|-------------|
| Quick Start | [Getting Started](#quick-start) | 5-minute integration guide |
| API Reference | [Documentation](https://sirstig.github.io/yokedcache) | Complete API documentation |
| Examples | [Examples](examples/) | Real-world usage examples |
| CLI Guide | [CLI Usage](#cli-usage) | Command-line tool documentation |
## Usage Examples
### Enhanced Configuration *(New in v0.2.1)*
```python
from yokedcache import YokedCache, CacheConfig
# Production-ready configuration with resilience features
config = CacheConfig(
redis_url="redis://localhost:6379",
max_connections=50,
# Circuit breaker for Redis failures
enable_circuit_breaker=True,
circuit_breaker_failure_threshold=5,
circuit_breaker_timeout=60.0,
# Enhanced connection pool settings
connection_pool_kwargs={
"socket_connect_timeout": 5.0,
"socket_timeout": 5.0,
"socket_keepalive": True,
"retry_on_timeout": True,
"health_check_interval": 30
},
# Error handling and fallbacks
fallback_enabled=True,
connection_retries=3,
retry_delay=0.1
)
cache = YokedCache(config=config)
# Monitor cache health
health = await cache.detailed_health_check()
print(f"Cache status: {health['status']}")
print(f"Connection pool: {health['connection_pool']}")
# Get comprehensive metrics
metrics = cache.get_comprehensive_metrics()
print(f"Hit rate: {metrics.hit_rate:.2%}")
print(f"Average response time: {metrics.avg_response_time:.3f}s")
```
### Explicit Async/Sync Methods *(New in v0.2.1)*
```python
# Explicit async methods (recommended in async contexts)
value = await cache.aget("user:123")
await cache.aset("user:123", user_data, ttl=300)
exists = await cache.aexists("user:123")
await cache.adelete("user:123")
# Explicit sync methods (for sync contexts)
value = cache.get_sync("user:123")
cache.set_sync("user:123", user_data, ttl=300)
exists = cache.exists_sync("user:123")
cache.delete_sync("user:123")
# Smart context-aware methods (auto-detect async/sync)
value = await cache.get("user:123") # In async context
value = cache.get("user:123") # In sync context
```
```python
from fastapi import FastAPI, Depends
from yokedcache import YokedCache, cached_dependency
app = FastAPI()
cache = YokedCache(redis_url="redis://localhost:6379/0")
# Wrap your existing database dependency
cached_get_db = cached_dependency(get_db, cache=cache, ttl=300)
@app.get("/users/{user_id}")
async def get_user(user_id: int, db=Depends(cached_get_db)):
# Your existing code works unchanged!
return db.query(User).filter(User.id == user_id).first()
# Automatic caching + invalidation now active!
```
### Advanced Usage
### Multi-Backend Configuration
```python
from yokedcache import YokedCache
from yokedcache.backends import RedisBackend, MemcachedBackend, MemoryBackend
# Redis backend (default)
redis_cache = YokedCache(backend=RedisBackend(
redis_url="redis://localhost:6379/0"
))
# Memcached backend
memcached_cache = YokedCache(backend=MemcachedBackend(
servers=["localhost:11211"]
))
# In-memory backend for development
memory_cache = YokedCache(backend=MemoryBackend(
max_size=1000 # Limit to 1000 keys
))
```
### Vector-Based Similarity Search
```python
from yokedcache.vector_search import VectorSimilaritySearch
# Initialize vector search
vector_search = VectorSimilaritySearch(
similarity_method="cosine", # or "euclidean", "manhattan"
max_features=1000
)
# Perform semantic search
results = await cache.vector_search(
query="user authentication",
threshold=0.5, # 50% similarity
max_results=10
)
```
### Production Monitoring
```python
from yokedcache.monitoring import PrometheusCollector, StatsDCollector, CacheMetrics
# Set up Prometheus monitoring
prometheus = PrometheusCollector(namespace="myapp")
cache_metrics = CacheMetrics([prometheus])
# Set up StatsD monitoring
statsd = StatsDCollector(host="statsd.example.com", prefix="myapp.cache")
cache_metrics.add_collector(statsd)
# Initialize cache with monitoring
cache = YokedCache(metrics=cache_metrics)
```
### Configuration with YAML
```yaml
# cache_config.yaml
default_ttl: 300
key_prefix: "myapp"
tables:
users:
ttl: 3600 # 1 hour for user data
tags: ["user_data"]
invalidate_on: ["insert", "update", "delete"]
```
### Manual Cache Control
```python
from yokedcache import YokedCache, cached
cache = YokedCache()
# Decorator caching
@cached(cache=cache, ttl=600, tags=["products"])
async def get_expensive_data(query: str):
return expensive_db_query(query)
# Manual operations
await cache.set("key", {"data": "value"}, ttl=300, tags=["api"])
data = await cache.get("key")
await cache.invalidate_tags(["products"])
```
## CLI Usage
YokedCache includes a powerful CLI for cache management:
```bash
# View cache statistics
yokedcache stats --watch
# Export stats to CSV for analysis
yokedcache stats --format csv --output cache_stats.csv
# Export stats to JSON for dashboards
yokedcache stats --format json --output stats.json
# Test connection to different backends
yokedcache ping --backend redis
yokedcache ping --backend memcached
# List cached keys with filtering
yokedcache list --pattern "user:*" --limit 50
# Flush specific caches by tags
yokedcache flush --tags "user_data,session_data"
# Advanced search with vector similarity
yokedcache search "user authentication" --method vector --threshold 0.5
# Traditional fuzzy search
yokedcache search "alice" --method fuzzy --threshold 80
# Monitor in real-time with CSV logging
yokedcache stats --format csv --output metrics.csv --watch
# Export current configuration
yokedcache export-config --output config.yaml
# Warm cache with predefined data
yokedcache warm --config-file cache_config.yaml
```
## Performance
| Metric | Improvement | Description |
|--------|-------------|-------------|
| Database Load | 60-90% reduction | Automatic query caching |
| Response Time | 200-500ms faster | Redis-fast cache hits |
| Memory Usage | Optimized | Efficient serialization |
| Setup Time | Under 5 minutes | Drop-in integration |
## Architecture
```mermaid
graph TB
A[FastAPI App] --> B[YokedCache Wrapper]
B --> C{Cache Hit?}
C -->|Yes| D[Return Cached Data]
C -->|No| E[Query Database]
E --> F[Store in Redis]
F --> G[Return Data]
H[Database Write] --> I[Auto-Invalidation]
I --> J[Clear Related Cache]
```
## Testing
YokedCache includes comprehensive test coverage for all features:
### Quick Verification
```bash
# Verify all features are working
python test_quick_verification.py
```
### Full Test Suite
```bash
# Install development dependencies
pip install yokedcache[dev]
# Run all tests
pytest
# Run with coverage
pytest --cov=yokedcache --cov-report=html
# Run specific feature tests
pytest tests/test_backends.py # Multi-backend tests
pytest tests/test_vector_search.py # Vector similarity tests
pytest tests/test_monitoring.py # Monitoring tests
pytest tests/test_cli.py # CLI tests
```
### Test Categories
- **Backend Tests**: Memory, Redis, Memcached implementations
- **Vector Search Tests**: TF-IDF, cosine similarity, semantic search
- **Monitoring Tests**: Prometheus, StatsD, metrics collection
- **CLI Tests**: CSV export, search commands, configuration
- **Integration Tests**: End-to-end workflows and error handling
For detailed testing information, see the [Testing Guide](docs/testing.md).
## Contributing
We welcome contributions! Here's how to get started:
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Commit your changes: `git commit -m "feat: add amazing feature"`
5. Push to the branch: `git push origin feature/amazing-feature`
6. Open a Pull Request
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
## Project Status
[](https://github.com/sirstig/yokedcache/stargazers)
[](https://github.com/sirstig/yokedcache/network/members)
[](https://github.com/sirstig/yokedcache/issues)
[](https://github.com/sirstig/yokedcache/pulls)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
**Made with care by [Project Yoked LLC](https://github.com/sirstig)**
Raw data
{
"_id": null,
"home_page": null,
"name": "yokedcache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cache, caching, database, fastapi, orm, performance, redis, sqlalchemy",
"author": "Project Yoked LLC",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a3/c0/34eb2ee1adadc277e8fd49754787b3848f64c7253cbe2fa62201597b5832/yokedcache-0.2.3.tar.gz",
"platform": null,
"description": "# YokedCache\n\nHigh-Performance Caching for Modern Python Applications\n\n<div align=\"center\">\n\n[](https://github.com/sirstig/yokedcache/stargazers)\n\n[](https://pypi.org/project/yokedcache/)\n[](https://pypi.org/project/yokedcache/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/sirstig/yokedcache/actions/workflows/test.yml)\n[](https://codecov.io/gh/sirstig/yokedcache)\n[](https://github.com/psf/black)\n\n\n</div>\n\nIntelligent caching with automatic invalidation, fuzzy search, and seamless FastAPI integration.\n\n**[Documentation](https://sirstig.github.io/yokedcache)** | **[Report Bug](https://github.com/sirstig/yokedcache/issues)** | **[Request Feature](https://github.com/sirstig/yokedcache/issues)**\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Documentation](#documentation)\n- [Usage Examples](#usage-examples)\n- [CLI Usage](#cli-usage)\n- [Performance](#performance)\n- [Architecture](#architecture)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Overview\n\nTraditional caching solutions require manual cache management and lack intelligent invalidation. YokedCache solves this with:\n\n- **Smart Auto-Invalidation**: Automatically detects database changes and invalidates related caches\n- **Multi-Backend Support**: Redis, Memcached, and in-memory backends for flexibility\n- **Zero-Code Integration**: Drop-in replacement for your existing database dependencies \n- **Intelligent Tagging**: Group and invalidate related caches effortlessly \n- **Advanced Search**: Traditional fuzzy search plus vector-based semantic similarity\n- **Production Monitoring**: Prometheus and StatsD integration for real-time metrics\n- **Professional Tooling**: Comprehensive CLI with CSV export and monitoring capabilities\n\n## Quick Start\n\n```bash\npip install yokedcache\n```\n\n```python\nfrom fastapi import FastAPI, Depends\nfrom yokedcache import cached_dependency\n\napp = FastAPI()\n\n# Replace your database dependency\ncached_get_db = cached_dependency(get_db, ttl=300)\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: int, db=Depends(cached_get_db)):\n # Your existing code - no changes needed!\n return db.query(User).filter(User.id == user_id).first()\n```\n\nThat's it! Your database queries are now cached with automatic invalidation.\n\n## Key Features\n\n### \ud83d\udd10 Production-Grade Resilience *(New in v0.2.1)*\n\n- **Circuit Breaker Pattern**: Prevents cascading failures during Redis outages\n- **Connection Pool Management**: Advanced Redis connection configuration\n- **Retry Logic**: Exponential backoff for transient failures\n- **Health Monitoring**: Comprehensive cache status and performance metrics\n- **Graceful Fallbacks**: Application stability during cache issues\n\n### \ud83d\udd04 Enhanced Async/Sync Support *(New in v0.2.1)*\n\n- **Smart Context Detection**: Prevents Task object returns in mixed environments\n- **Explicit Method Variants**: `aget`/`aset` for async, `get_sync`/`set_sync` for sync\n- **FastAPI Generator Support**: Better handling of database session dependencies\n- **Performance Optimization**: Improved serialization and key generation\n\n### Multi-Backend Architecture\n\n- **Redis**: Full-featured backend with clustering and persistence support\n- **Memcached**: High-performance distributed caching\n- **In-Memory**: Fast local caching for development and testing\n- Pluggable backend system for custom implementations\n\n### Smart Invalidation\n\n- Automatic cache invalidation on database writes\n- Tag-based grouping for related data\n- Pattern-based invalidation with wildcards\n- Configurable rules per table/operation\n\n### Advanced Search Capabilities\n\n- Traditional fuzzy search with configurable thresholds\n- Vector-based semantic similarity using TF-IDF and cosine similarity\n- Multiple similarity algorithms (cosine, euclidean, manhattan)\n- Redis vector persistence for large-scale deployments\n\n### Deep Integration\n\n- Zero-code FastAPI integration\n- SQLAlchemy ORM support\n- Async/await throughout\n- Connection pooling & health checks\n\n### Production Monitoring\n\n- **Prometheus**: Native metrics export for Grafana dashboards\n- **StatsD**: Real-time metrics for DataDog, Grafana, and other platforms\n- Comprehensive performance tracking and alerting\n- Custom metrics collection support\n\n### Professional Tooling\n\n- Comprehensive CLI for cache control and monitoring\n- CSV export for data analysis and reporting\n- Real-time statistics with watch mode\n- YAML-based configuration with validation\n- Cache warming and bulk operations\n\n## Installation\n\n```bash\n# Basic installation (Redis backend only)\npip install yokedcache\n\n# With specific features\npip install yokedcache[memcached] # Add Memcached support\npip install yokedcache[monitoring] # Add Prometheus/StatsD support \npip install yokedcache[vector] # Add vector similarity search\npip install yokedcache[fuzzy] # Add traditional fuzzy search\n\n# Full installation with all features\npip install yokedcache[full]\n\n# Development installation\npip install yokedcache[dev]\n```\n\n## Documentation\n\n| Guide | Link | Description |\n|-------|------|-------------|\n| Quick Start | [Getting Started](#quick-start) | 5-minute integration guide |\n| API Reference | [Documentation](https://sirstig.github.io/yokedcache) | Complete API documentation |\n| Examples | [Examples](examples/) | Real-world usage examples |\n| CLI Guide | [CLI Usage](#cli-usage) | Command-line tool documentation |\n\n## Usage Examples\n\n### Enhanced Configuration *(New in v0.2.1)*\n\n```python\nfrom yokedcache import YokedCache, CacheConfig\n\n# Production-ready configuration with resilience features\nconfig = CacheConfig(\n redis_url=\"redis://localhost:6379\",\n max_connections=50,\n \n # Circuit breaker for Redis failures\n enable_circuit_breaker=True,\n circuit_breaker_failure_threshold=5,\n circuit_breaker_timeout=60.0,\n \n # Enhanced connection pool settings\n connection_pool_kwargs={\n \"socket_connect_timeout\": 5.0,\n \"socket_timeout\": 5.0,\n \"socket_keepalive\": True,\n \"retry_on_timeout\": True,\n \"health_check_interval\": 30\n },\n \n # Error handling and fallbacks\n fallback_enabled=True,\n connection_retries=3,\n retry_delay=0.1\n)\n\ncache = YokedCache(config=config)\n\n# Monitor cache health\nhealth = await cache.detailed_health_check()\nprint(f\"Cache status: {health['status']}\")\nprint(f\"Connection pool: {health['connection_pool']}\")\n\n# Get comprehensive metrics\nmetrics = cache.get_comprehensive_metrics()\nprint(f\"Hit rate: {metrics.hit_rate:.2%}\")\nprint(f\"Average response time: {metrics.avg_response_time:.3f}s\")\n```\n\n### Explicit Async/Sync Methods *(New in v0.2.1)*\n\n```python\n# Explicit async methods (recommended in async contexts)\nvalue = await cache.aget(\"user:123\")\nawait cache.aset(\"user:123\", user_data, ttl=300)\nexists = await cache.aexists(\"user:123\")\nawait cache.adelete(\"user:123\")\n\n# Explicit sync methods (for sync contexts)\nvalue = cache.get_sync(\"user:123\")\ncache.set_sync(\"user:123\", user_data, ttl=300)\nexists = cache.exists_sync(\"user:123\")\ncache.delete_sync(\"user:123\")\n\n# Smart context-aware methods (auto-detect async/sync)\nvalue = await cache.get(\"user:123\") # In async context\nvalue = cache.get(\"user:123\") # In sync context\n```\n\n```python\nfrom fastapi import FastAPI, Depends\nfrom yokedcache import YokedCache, cached_dependency\n\napp = FastAPI()\ncache = YokedCache(redis_url=\"redis://localhost:6379/0\")\n\n# Wrap your existing database dependency\ncached_get_db = cached_dependency(get_db, cache=cache, ttl=300)\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: int, db=Depends(cached_get_db)):\n # Your existing code works unchanged!\n return db.query(User).filter(User.id == user_id).first()\n\n# Automatic caching + invalidation now active!\n```\n\n### Advanced Usage\n\n### Multi-Backend Configuration\n\n```python\nfrom yokedcache import YokedCache\nfrom yokedcache.backends import RedisBackend, MemcachedBackend, MemoryBackend\n\n# Redis backend (default)\nredis_cache = YokedCache(backend=RedisBackend(\n redis_url=\"redis://localhost:6379/0\"\n))\n\n# Memcached backend\nmemcached_cache = YokedCache(backend=MemcachedBackend(\n servers=[\"localhost:11211\"]\n))\n\n# In-memory backend for development\nmemory_cache = YokedCache(backend=MemoryBackend(\n max_size=1000 # Limit to 1000 keys\n))\n```\n\n### Vector-Based Similarity Search\n\n```python\nfrom yokedcache.vector_search import VectorSimilaritySearch\n\n# Initialize vector search\nvector_search = VectorSimilaritySearch(\n similarity_method=\"cosine\", # or \"euclidean\", \"manhattan\"\n max_features=1000\n)\n\n# Perform semantic search\nresults = await cache.vector_search(\n query=\"user authentication\",\n threshold=0.5, # 50% similarity\n max_results=10\n)\n```\n\n### Production Monitoring\n\n```python\nfrom yokedcache.monitoring import PrometheusCollector, StatsDCollector, CacheMetrics\n\n# Set up Prometheus monitoring\nprometheus = PrometheusCollector(namespace=\"myapp\")\ncache_metrics = CacheMetrics([prometheus])\n\n# Set up StatsD monitoring \nstatsd = StatsDCollector(host=\"statsd.example.com\", prefix=\"myapp.cache\")\ncache_metrics.add_collector(statsd)\n\n# Initialize cache with monitoring\ncache = YokedCache(metrics=cache_metrics)\n```\n\n### Configuration with YAML\n\n```yaml\n# cache_config.yaml\ndefault_ttl: 300\nkey_prefix: \"myapp\"\n\ntables:\n users:\n ttl: 3600 # 1 hour for user data\n tags: [\"user_data\"]\n invalidate_on: [\"insert\", \"update\", \"delete\"]\n```\n\n### Manual Cache Control\n\n```python\nfrom yokedcache import YokedCache, cached\n\ncache = YokedCache()\n\n# Decorator caching\n@cached(cache=cache, ttl=600, tags=[\"products\"])\nasync def get_expensive_data(query: str):\n return expensive_db_query(query)\n\n# Manual operations\nawait cache.set(\"key\", {\"data\": \"value\"}, ttl=300, tags=[\"api\"])\ndata = await cache.get(\"key\")\nawait cache.invalidate_tags([\"products\"])\n```\n\n## CLI Usage\n\nYokedCache includes a powerful CLI for cache management:\n\n```bash\n# View cache statistics\nyokedcache stats --watch\n\n# Export stats to CSV for analysis\nyokedcache stats --format csv --output cache_stats.csv\n\n# Export stats to JSON for dashboards \nyokedcache stats --format json --output stats.json\n\n# Test connection to different backends\nyokedcache ping --backend redis\nyokedcache ping --backend memcached\n\n# List cached keys with filtering\nyokedcache list --pattern \"user:*\" --limit 50\n\n# Flush specific caches by tags\nyokedcache flush --tags \"user_data,session_data\"\n\n# Advanced search with vector similarity\nyokedcache search \"user authentication\" --method vector --threshold 0.5\n\n# Traditional fuzzy search\nyokedcache search \"alice\" --method fuzzy --threshold 80\n\n# Monitor in real-time with CSV logging\nyokedcache stats --format csv --output metrics.csv --watch\n\n# Export current configuration\nyokedcache export-config --output config.yaml\n\n# Warm cache with predefined data\nyokedcache warm --config-file cache_config.yaml\n```\n\n## Performance\n\n| Metric | Improvement | Description |\n|--------|-------------|-------------|\n| Database Load | 60-90% reduction | Automatic query caching |\n| Response Time | 200-500ms faster | Redis-fast cache hits |\n| Memory Usage | Optimized | Efficient serialization |\n| Setup Time | Under 5 minutes | Drop-in integration |\n\n## Architecture\n\n```mermaid\ngraph TB\n A[FastAPI App] --> B[YokedCache Wrapper]\n B --> C{Cache Hit?}\n C -->|Yes| D[Return Cached Data]\n C -->|No| E[Query Database]\n E --> F[Store in Redis]\n F --> G[Return Data]\n H[Database Write] --> I[Auto-Invalidation]\n I --> J[Clear Related Cache]\n```\n\n## Testing\n\nYokedCache includes comprehensive test coverage for all features:\n\n### Quick Verification\n\n```bash\n# Verify all features are working\npython test_quick_verification.py\n```\n\n### Full Test Suite\n\n```bash\n# Install development dependencies\npip install yokedcache[dev]\n\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=yokedcache --cov-report=html\n\n# Run specific feature tests\npytest tests/test_backends.py # Multi-backend tests\npytest tests/test_vector_search.py # Vector similarity tests\npytest tests/test_monitoring.py # Monitoring tests\npytest tests/test_cli.py # CLI tests\n```\n\n### Test Categories\n\n- **Backend Tests**: Memory, Redis, Memcached implementations\n- **Vector Search Tests**: TF-IDF, cosine similarity, semantic search\n- **Monitoring Tests**: Prometheus, StatsD, metrics collection\n- **CLI Tests**: CSV export, search commands, configuration\n- **Integration Tests**: End-to-end workflows and error handling\n\nFor detailed testing information, see the [Testing Guide](docs/testing.md).\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Commit your changes: `git commit -m \"feat: add amazing feature\"`\n5. Push to the branch: `git push origin feature/amazing-feature`\n6. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## Project Status\n\n[](https://github.com/sirstig/yokedcache/stargazers)\n[](https://github.com/sirstig/yokedcache/network/members)\n[](https://github.com/sirstig/yokedcache/issues)\n[](https://github.com/sirstig/yokedcache/pulls)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Made with care by [Project Yoked LLC](https://github.com/sirstig)**\n",
"bugtrack_url": null,
"license": null,
"summary": "A robust, performance-focused caching library for Python backends with FastAPI integration",
"version": "0.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/sirstig/yokedcache/issues",
"Documentation": "https://sirstig.github.io/yokedcache",
"Homepage": "https://github.com/sirstig/yokedcache",
"Repository": "https://github.com/sirstig/yokedcache"
},
"split_keywords": [
"cache",
" caching",
" database",
" fastapi",
" orm",
" performance",
" redis",
" sqlalchemy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c4b89ad48a5994d1badb2acbc1fb060421b7f4bb6df6798d8b1222c4cddec4ac",
"md5": "8f23d83423b0f31fded7a7bef071d9d1",
"sha256": "9d4ef057dbedebd273dfe145aaaf2a0b3eab3650e0bf7f3f90a938f8d3928a6c"
},
"downloads": -1,
"filename": "yokedcache-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f23d83423b0f31fded7a7bef071d9d1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 66063,
"upload_time": "2025-08-25T22:41:05",
"upload_time_iso_8601": "2025-08-25T22:41:05.561893Z",
"url": "https://files.pythonhosted.org/packages/c4/b8/9ad48a5994d1badb2acbc1fb060421b7f4bb6df6798d8b1222c4cddec4ac/yokedcache-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a3c034eb2ee1adadc277e8fd49754787b3848f64c7253cbe2fa62201597b5832",
"md5": "af153580433f912fee8e37b7f0c02396",
"sha256": "677949c4654482714639c7c618095a034f9990334e0fe2c20aafc129dd4b726d"
},
"downloads": -1,
"filename": "yokedcache-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "af153580433f912fee8e37b7f0c02396",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 179385,
"upload_time": "2025-08-25T22:41:06",
"upload_time_iso_8601": "2025-08-25T22:41:06.809334Z",
"url": "https://files.pythonhosted.org/packages/a3/c0/34eb2ee1adadc277e8fd49754787b3848f64c7253cbe2fa62201597b5832/yokedcache-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 22:41:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sirstig",
"github_project": "yokedcache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "yokedcache"
}
JSON
