orion-cache 0.1.7
Shared Redis cache decorator for internal Python services — write once, import everywhere.
License: MIT
Requires Python: >=3.9
Keywords: redis, cache, decorator, caching

# orion-cache

> Shared Redis cache decorator for Python services — write once, import everywhere.

[![PyPI version](https://img.shields.io/pypi/v/orion-cache)](https://pypi.org/project/orion-cache/)
[![Python](https://img.shields.io/pypi/pyversions/orion-cache)](https://pypi.org/project/orion-cache/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## What is it?

`orion-cache` is a lightweight Python library that wraps Redis caching behind a simple decorator. Slap `@redis_cache()` on any function and its return value is automatically cached in Redis — no boilerplate, no repeated logic across services.

Built for multiple services that query the same database and want to share cached results without duplicating caching code.

---

## Installation

```bash
pip install orion-cache
```

---

## Quick Start

```python
from orion_cache import redis_cache, clear_all_caches

@redis_cache(ttl=300)
def get_orders(customer):
    return db.query("SELECT * FROM orders WHERE customer = ?", customer)

@redis_cache()  # uses default TTL (300s)
def get_all_products():
    return db.query("SELECT * FROM products")
```

First call hits the database and caches the result. Every call after that is served from Redis until the TTL expires.

---

## Clear Cache

```python
# clear everything
clear_all_caches()

# clear only keys matching a pattern
clear_all_caches(pattern="get_orders:*")
```

---

## Configuration

`orion-cache` is configured via environment variables. Create a `.env` file in your project root or set them in your environment directly.

| Variable | Default | Description |
|---|---|---|
| `REDIS_HOST` | `localhost` | Redis server hostname |
| `REDIS_PORT` | `6379` | Redis server port |
| `REDIS_PASSWORD` | _(none)_ | Redis password |
| `REDIS_DB` | `0` | Redis database index |
| `CACHE_DEFAULT_TTL` | `300` | Default TTL in seconds |
| `REDIS_URL` | _(auto-built)_ | Full Redis URL — overrides all above if set |

**.env example:**
```env
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=secret
CACHE_DEFAULT_TTL=300
```

Or use a full URL:
```env
REDIS_URL=redis://:secret@your-redis-host:6379/0
```

In production (Docker, k8s), set real environment variables instead of a `.env` file — the library will pick them up automatically.

---

## Sharing Cache Across Services

If multiple services point at the same Redis instance and use the same function names, they will automatically share cached results — no extra configuration needed.

If two services have different functions with the same name that do different things, use descriptive function names to avoid collisions:

```python
# good
def orders_get_all(): ...
def products_get_all(): ...

# risky if shared Redis
def get_all(): ...
```

---

## Behavior

- **Cache miss:** calls the real function, stores result in Redis, returns result
- **Cache hit:** returns cached result directly, function is never called
- **Redis down:** fails silently, falls through to the real function — your app keeps working
- **Non-serializable types** (e.g. `datetime`, `UUID`): automatically converted to string via `default=str`

---

## Requirements

- Python 3.9+
- Redis 5+

---

## Contributing

Contributions are welcome!

1. Fork the repo and clone it locally
2. Create a virtual environment and install in editable mode:
   ```bash
   python -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   ```
3. Make your changes
4. Run tests before submitting:
   ```bash
   pytest
   ```
5. Open a pull request against `main`

Please keep PRs focused — one feature or fix per PR.

For bugs or feature requests, open an issue on [GitHub](https://github.com/aliinreallife/orion-cache/issues).

---

## License

MIT © [Ali Rashidi](mailto:aliinreallifee@gmail.com)