<div align="center">
# 🚀 YokedCache
**High-Performance Caching for Modern Python Applications**
[](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://github.com/psf/black)
[](https://pypi.org/project/yokedcache/)
*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)
</div>
---
## 🎯 **Why YokedCache?**
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
⚡ **Zero-Code Integration** - Drop-in replacement for your existing database dependencies
🎯 **Intelligent Tagging** - Group and invalidate related caches effortlessly
🔍 **Fuzzy Search** - Find cached data with approximate matching
📊 **Performance Insights** - Built-in metrics and monitoring tools
## ⚡ **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. 🎉
## ✨ **Features**
<table>
<tr>
<td width="50%">
### 🔄 **Smart Invalidation**
- Automatic cache invalidation on database writes
- Tag-based grouping for related data
- Pattern-based invalidation with wildcards
- Configurable rules per table/operation
### 🎯 **Deep Integration**
- Zero-code FastAPI integration
- SQLAlchemy ORM support
- Async/await throughout
- Connection pooling & health checks
</td>
<td width="50%">
### 🔍 **Advanced Features**
- Fuzzy search for approximate matches
- Multiple serialization methods
- Performance metrics & monitoring
- Variable TTLs with jitter
### 🖥️ **Management Tools**
- Comprehensive CLI for cache control
- Real-time statistics and monitoring
- YAML-based configuration
- Cache warming capabilities
</td>
</tr>
</table>
## 📦 **Installation**
```bash
# 🚀 Basic installation
pip install yokedcache
# 🔧 With optional features
pip install yokedcache[sqlalchemy,fuzzy] # Full-featured
# 👨💻 Development
pip install yokedcache[dev]
```
## 📖 **Documentation**
<div align="center">
| 📚 **Guide** | 🔗 **Link** | 📝 **Description** |
|-------------|------------|-------------------|
| **Quick Start** | [Getting Started](#-quick-start) | 5-minute integration guide |
| **API Reference** | [Docs](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 |
</div>
## 🎬 **Live Demo**
```python
from fastapi import FastAPI, Depends
from yokedcache import YokedCache, cached_dependency
app = FastAPI()
cache = YokedCache(redis_url="redis://localhost:6379/0")
# 1️⃣ 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)):
# 2️⃣ Your existing code works unchanged!
return db.query(User).filter(User.id == user_id).first()
# 🎉 Automatic caching + invalidation now active!
```
## 🔧 **Advanced Usage**
### 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
# Test Redis connection
yokedcache ping
# List cached keys
yokedcache list --pattern "user:*"
# Flush specific caches
yokedcache flush --tags "user_data"
# Search cache contents
yokedcache search "alice" --threshold 80
# Monitor in real-time (JSON output for dashboards)
yokedcache stats --format json
# Export current configuration
yokedcache export-config --output config.yaml
# Warm cache with predefined data
yokedcache warm --config-file cache_config.yaml
```
## 🚀 **Performance**
<div align="center">
| **Metric** | **Improvement** | **Description** |
|------------|----------------|-----------------|
| **Database Load** | ↓ 60-90% | Automatic query caching |
| **Response Time** | ↓ 200-500ms | Redis-fast cache hits |
| **Memory Usage** | Optimized | Efficient serialization |
| **Setup Time** | < 5 minutes | Drop-in integration |
</div>
## 🏗️ **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**
```bash
# Install with dev dependencies
pip install yokedcache[dev]
# Run tests
pytest
# Run with coverage
pytest --cov=yokedcache
# Test specific functionality
pytest tests/test_cache.py::TestAutoInvalidation
```
## 🤝 **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**
<div align="center">
[](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)
</div>
## 📄 **License**
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
## 🙏 **Acknowledgments**
- **Redis** - For the excellent caching backend
- **FastAPI** - For the amazing Python web framework
- **SQLAlchemy** - For database ORM integration
- **Python Community** - For continuous inspiration and feedback
---
<div align="center">
**Made with ❤️ by [Project Yoked LLC](https://github.com/sirstig)**
*If YokedCache helps your project, please consider giving it a ⭐ on GitHub!*
</div>
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/62/0c/8c32d3ed59eb950c6ac3efb09aa0856d01373844340ebde4c83b4bfa76ac/yokedcache-0.1.3.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# \ud83d\ude80 YokedCache\n\n**High-Performance Caching for Modern Python Applications**\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://github.com/psf/black)\n[](https://pypi.org/project/yokedcache/)\n\n*Intelligent caching with automatic invalidation, fuzzy search, and seamless FastAPI integration*\n\n[\ud83d\udcda Documentation](https://sirstig.github.io/yokedcache) \u2022 [\ud83d\udc1b Report Bug](https://github.com/sirstig/yokedcache/issues) \u2022 [\u2728 Request Feature](https://github.com/sirstig/yokedcache/issues)\n\n</div>\n\n---\n\n## \ud83c\udfaf **Why YokedCache?**\n\nTraditional caching solutions require manual cache management and lack intelligent invalidation. **YokedCache** solves this with:\n\n\ud83d\udd04 **Smart Auto-Invalidation** - Automatically detects database changes and invalidates related caches \n\u26a1 **Zero-Code Integration** - Drop-in replacement for your existing database dependencies \n\ud83c\udfaf **Intelligent Tagging** - Group and invalidate related caches effortlessly \n\ud83d\udd0d **Fuzzy Search** - Find cached data with approximate matching \n\ud83d\udcca **Performance Insights** - Built-in metrics and monitoring tools\n\n## \u26a1 **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\n**That's it!** Your database queries are now cached with automatic invalidation. \ud83c\udf89\n\n## \u2728 **Features**\n\n<table>\n<tr>\n<td width=\"50%\">\n\n### \ud83d\udd04 **Smart Invalidation**\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### \ud83c\udfaf **Deep Integration** \n- Zero-code FastAPI integration\n- SQLAlchemy ORM support\n- Async/await throughout\n- Connection pooling & health checks\n\n</td>\n<td width=\"50%\">\n\n### \ud83d\udd0d **Advanced Features**\n- Fuzzy search for approximate matches\n- Multiple serialization methods\n- Performance metrics & monitoring\n- Variable TTLs with jitter\n\n### \ud83d\udda5\ufe0f **Management Tools**\n- Comprehensive CLI for cache control\n- Real-time statistics and monitoring\n- YAML-based configuration\n- Cache warming capabilities\n\n</td>\n</tr>\n</table>\n\n## \ud83d\udce6 **Installation**\n\n```bash\n# \ud83d\ude80 Basic installation\npip install yokedcache\n\n# \ud83d\udd27 With optional features\npip install yokedcache[sqlalchemy,fuzzy] # Full-featured\n\n# \ud83d\udc68\u200d\ud83d\udcbb Development\npip install yokedcache[dev]\n```\n\n## \ud83d\udcd6 **Documentation**\n\n<div align=\"center\">\n\n| \ud83d\udcda **Guide** | \ud83d\udd17 **Link** | \ud83d\udcdd **Description** |\n|-------------|------------|-------------------|\n| **Quick Start** | [Getting Started](#-quick-start) | 5-minute integration guide |\n| **API Reference** | [Docs](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</div>\n\n## \ud83c\udfac **Live Demo**\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# 1\ufe0f\u20e3 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 # 2\ufe0f\u20e3 Your existing code works unchanged!\n return db.query(User).filter(User.id == user_id).first()\n\n# \ud83c\udf89 Automatic caching + invalidation now active!\n```\n\n## \ud83d\udd27 **Advanced Usage**\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## \ud83d\udda5\ufe0f **CLI Usage**\n\nYokedCache includes a powerful CLI for cache management:\n\n```bash\n# View cache statistics\nyokedcache stats --watch\n\n# Test Redis connection\nyokedcache ping\n\n# List cached keys\nyokedcache list --pattern \"user:*\"\n\n# Flush specific caches\nyokedcache flush --tags \"user_data\"\n\n# Search cache contents\nyokedcache search \"alice\" --threshold 80\n\n# Monitor in real-time (JSON output for dashboards)\nyokedcache stats --format json\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## \ud83d\ude80 **Performance**\n\n<div align=\"center\">\n\n| **Metric** | **Improvement** | **Description** |\n|------------|----------------|-----------------|\n| **Database Load** | \u2193 60-90% | Automatic query caching |\n| **Response Time** | \u2193 200-500ms | Redis-fast cache hits |\n| **Memory Usage** | Optimized | Efficient serialization |\n| **Setup Time** | < 5 minutes | Drop-in integration |\n\n</div>\n\n## \ud83c\udfd7\ufe0f **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## \ud83e\uddea **Testing**\n\n```bash\n# Install with dev dependencies\npip install yokedcache[dev]\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=yokedcache\n\n# Test specific functionality\npytest tests/test_cache.py::TestAutoInvalidation\n```\n\n## \ud83e\udd1d **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## \ud83d\udcca **Project Status**\n\n<div align=\"center\">\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</div>\n\n## \ud83d\udcc4 **License**\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f **Acknowledgments**\n\n- **Redis** - For the excellent caching backend\n- **FastAPI** - For the amazing Python web framework\n- **SQLAlchemy** - For database ORM integration\n- **Python Community** - For continuous inspiration and feedback\n\n---\n\n<div align=\"center\">\n\n**Made with \u2764\ufe0f by [Project Yoked LLC](https://github.com/sirstig)**\n\n*If YokedCache helps your project, please consider giving it a \u2b50 on GitHub!*\n\n</div>\n",
"bugtrack_url": null,
"license": null,
"summary": "A robust, performance-focused caching library for Python backends with FastAPI integration",
"version": "0.1.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": "3cbb19ecfd07ec8e7aca3b2dfce9d627795ca8b98a7cc174987c26b00a101326",
"md5": "6e4a221acff34f8534a3bcd734d3e16f",
"sha256": "a82c93ef7578ecef3d76bf27ab6d2e054efe1d2d2cec2b20371c49e68bc5d668"
},
"downloads": -1,
"filename": "yokedcache-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e4a221acff34f8534a3bcd734d3e16f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 30077,
"upload_time": "2025-08-22T23:20:29",
"upload_time_iso_8601": "2025-08-22T23:20:29.524762Z",
"url": "https://files.pythonhosted.org/packages/3c/bb/19ecfd07ec8e7aca3b2dfce9d627795ca8b98a7cc174987c26b00a101326/yokedcache-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "620c8c32d3ed59eb950c6ac3efb09aa0856d01373844340ebde4c83b4bfa76ac",
"md5": "79b325ea78c5fb2b4013cd6b8035b378",
"sha256": "6b4bb2bdc19acfe1c96cd070b4bf39e1e760a0345ee73c201ca967112b2b368a"
},
"downloads": -1,
"filename": "yokedcache-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "79b325ea78c5fb2b4013cd6b8035b378",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 43415,
"upload_time": "2025-08-22T23:20:30",
"upload_time_iso_8601": "2025-08-22T23:20:30.540061Z",
"url": "https://files.pythonhosted.org/packages/62/0c/8c32d3ed59eb950c6ac3efb09aa0856d01373844340ebde4c83b4bfa76ac/yokedcache-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 23:20:30",
"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
