orion-cache 0.1.7

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

orion-cache

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

---

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

pip install orion-cache

---

Quick Start

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

# 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:

REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=secret
CACHE_DEFAULT_TTL=300

Or use a full URL:

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:

# 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:

   python -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   

3. Make your changes
4. Run tests before submitting:

   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.

---

License

MIT © Ali Rashidi