cachefy 0.0.2

Asynchronous cache for Python, where a store that blinked is never a failure the caller sees.

🚀 Project

Cachefy is a cache built around one row: a name that holds a value until an instant.

A read is that row before that instant. A write replaces it. A miss is that row absent or past its instant. Memoizing a function, holding a name so exactly one caller computes, and counting a rate limit are all the same row under different values.

Two promises run through the whole of it:

• A store that cannot be reached is a miss and never an exception. A cache is what makes an application faster, not what makes it work.
• A value that could never be written is refused where it is written. That is a bug in the calling code, and it is told at once.

✨ Features

• Read, write and drop a value under a name, with a lifetime per space or per call
• Memoize a function on the arguments it was called with, and invalidate one call or all of them
• One caller computes while the rest wait, so a cold key never becomes a stampede
• Stale-while-revalidate: one caller refreshes while everybody else is served what is there
• Compare-and-set, so a slow writer never overwrites a newer value
• Atomic counters for rate limits and quotas
• Named spaces, cleared whole in one step
• Hooks for hits, misses and every call a store could not answer
• Pluggable stores: PostgreSQL, MySQL, Redis, SQLite and memory
• A value of None is a value, told apart from a name holding nothing
• No dependencies in the core
• 100% branch coverage: one contract against every store, plus differential, concurrency, interrupted-call, contention, resilience and multi-process suites

📦 Install

pip install "cachefy[redis]"

Or with SQLAlchemy:

pip install "cachefy[sqlalchemy]"

🧭 The five things it does

💡 How to use

import asyncio
from datetime import timedelta

from redis.asyncio import Redis

from cachefy.app import Cachefy
from cachefy.store.redis import RedisStore

app = Cachefy(RedisStore(Redis.from_url("redis://127.0.0.1:6379/0")))

users = app.space("users", ttl=timedelta(minutes=5), stale=timedelta(minutes=1))


@app.cached("profile", ttl=timedelta(minutes=5))
async def profile(user_id: int) -> dict:
    return {"id": user_id, "name": "Paulo"}


async def main():
    await app.setup()

    await users.set("42", {"name": "Paulo"})
    print(await users.get("42"))
    print(await profile(42))

    await profile.invalidate(42)


asyncio.run(main())

🧱 The words it uses

Four of them, and each means one thing:

📚 Documentation

• Getting started
• Spaces — lifetimes, freshness and every call a space answers
• Memoizing — caching what a function answered
• Stampede — one caller computes, and what everybody else is served
• Resilience — what happens when the store is gone
• Stores — Redis, SQLAlchemy, memory, and writing your own
• Janitor — sweeping what has died
• Hooks — hits, misses and failures
• Frameworks — the rule that covers all of them
  • FastAPI — the lifespan, and caching a response
  • Django — the ORM from a producer, and a management command
  • Flask — a synchronous world, and where the loop lives
• Contribution — how to help

🏷️ Releasing a new version

A release is a tag and nothing else. Bump project.version in pyproject.toml, commit it, then push the matching tag:

git tag v1.0.1
git push origin v1.0.1

That tag is the only trigger. The workflow then runs the suite on every supported Python against real Redis, MySQL and PostgreSQL, runs the stress suite against them, checks that the tag agrees with pyproject.toml, builds the wheel and the sdist, publishes them to PyPI through Trusted Publishing, and creates the GitHub release with its notes and the built files attached.

Do not publish the release from the GitHub interface. Creating one there writes the tag, the tag starts the workflow, and the workflow then finds a release already sitting where it was going to write its own. Push the tag and let the workflow create the release.

A version on PyPI is permanent. A tag that disagrees with project.version is refused before anything is built, because a number published by mistake is one PyPI never lets anybody use again.

☕ Buy me a coffee

Support the continuous development of this project.

📄 License

MIT

Copyright (c) 2026, Paulo Coutinho