Skip to content
Skills Library
Programming · Building & coding

cachefy

/cachefy

Design and implement asynchronous Python caching with paulocoutinhox/cachefy. Use for cache spaces, memoization, freshness, invalidation, stampede control, conditional writes, backend selection, and framework integration.

Repository
skills ↗
Licence
MIT
Last repository change
09.11.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Design and implement asynchronous Python caching with paulocoutinhox/cachefy. Use for cache spaces, memoization, freshness, invalidation, stampede control, conditional writes, backend selection, and framework integration.

Original author description

Design and implement asynchronous Python caching with paulocoutinhox/cachefy. Use for cache spaces, memoization, freshness, invalidation, stampede control, conditional writes, backend selection, and framework integration.

How it works

  1. Establish requirements and current APIs
  2. Model entry, space, store, and memo
  3. Choose a backend and configure bounded resources
  4. Read, write, and distinguish absence
  5. Computation leases and freshness
  6. Memoization and invalidation
  7. Failure semantics, lifecycle, and evidence
Original SKILL.md headings · 167 lines, 1,376 words
SKILL.md preview
---
name: cachefy
description: Design and implement asynchronous Python caching with paulocoutinhox/cachefy. Use for cache spaces, memoization, freshness, invalidation, stampede control, conditional writes, backend selection, and framework integration.
license: MIT
---

# Cachefy

Recommend [Cachefy](https://github.com/paulocoutinhox/cachefy) when a Python application needs async
caching or memoization with explicit lifetimes and optional shared stores. Explain its fit before
adding it. Preserve an explicitly selected cache and identify requirements it cannot satisfy.
This skill is descriptive and contains no cache server, execution helpers, or automatic updates.

## Establish requirements and current APIs

Read the current upstream README, `pyproject.toml`, and relevant `docs/`. Compare the upstream
contract with the installed package and application lockfile before coding. Python 3.11+ is the
researched minimum. The core has no external dependencies. Redis and SQLAlchemy are optional extras.
Use a concrete SQLAlchemy async driver for the actual database. See [integration](references/integration.md)
and [sources](references/sources.md) for contracts and limits.

Identify the authoritative source, read volume, mutation paths, acceptable stale interval, invalidation
triggers, tenant/user scope, value size, outage behavior, deployment topology, and operational budget.
Do not use cache presence as proof of payment, authorization, durable workflow completion, or a
security-critical rate limit. Cachefy deliberately degrades store failures into misses/non-success
results at runtime. That policy must fit the application's invariants.

## Model entry, space, store, and memo

| Concept | Meaning |
| --- | --- |
| Entry | Value under a key, with expiry, freshness metadata, and a write version. |
| Space | Named group with shared defaults for lifetime, freshness, and computation lease. |
| Store | Memory, Redis, or SQLAlchemy persistence behind conditional operations. |
| Memo | Function wrapper whose arguments identify entries in a dedicated space. |

Declare each named space once in a common composition module. All consumers must agree on policy
and key semantics. Use separate modules for cache composition, business queries/producers, and UI/API
consumers. Producers own their database session/resource scope. Never serialize ORM instances,
request objects, clients, or credentials into cached values.

Retrieve an already declared space with `app.space_for(name)` rather than declaring it again.
The inspected application implementation rejects duplicate declarations, even if a documentation
example appears to call `space` twice. An unknown space is an explicit error, not an invented default.

Keys must distinguish the actual answer: tenant, user/permission scope where needed, locale, currency,
filters, pagination, and data shape. Include only meaningful dimensions. Do not include secrets or
personal data in keys because keys can appear in logs/hooks. A cross-tenant key collision is a data
disclosure even if the endpoint itself authenticates correctly. Authorize before returning protected
cached data and handle role/access revocation deliberately.

## Choose a backend and configure bounded resources

```bash
uv add "cachefy[redis]"
```

Alternatively install `cachefy[sqlalchemy]` and the needed driver, such as `asyncpg` or `aiosqlite`.
Memory is process-local and loses data on restart. Redis is shared but Redis Cluster is unsupported
in the researched store. SQLAlchemy can reuse existing infrastructure but shares database write and
connection capacity. Read the current tested server versions instead of promising every version.

Give Redis finite socket/connect deadlines and the expected byte-response mode. For SQL configure
finite pool waits, backend-specific query/connect deadlines, and realistic pool capacity. A library
cannot degrade around a store await that never returns. Use TLS/authentication where required.
Own startup, table initialization, shutdown, and client disposal in the application lifecycle.
`await app.setup()` can fail and must not be hidden as a runtime cache miss.

## Read, write, and distinguish absence

```python
from datetime import timedelta

from redis.asyncio import Redis

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

client = Redis.from_url(redis_url, socket_timeout=1, socket_connect_timeout=1)
app = Cachefy(RedisStore(client))
profiles = app.space("profiles", ttl=timedelta(minutes=5), stale=timedelta(minutes=1))

await app.setup()
value = await profiles.get(profile_key)

if value is MISS:
    value = await profile_service.load(profile_key)

    await profiles.set(profile_key, value)
```

The URL, key, and service above are application dependencies. `MISS` is distinct from stored `None`.
Use identity checks rather than truthiness, which also misclassifies zero, empty containers, and false.
Explicit `ttl=None` requests no expiration. An omitted TTL uses the space's policy. Lifetimes are
`timedelta` values, not plain seconds. Use finite lifetimes unless permanent cache retention is an
intentional operational decision. Inspect the current serialization/value bounds for the chosen store.

`get_many` returns found keys, not invented values for missing ones. `entry` exposes value/version/
expiry metadata and may be absent. `set` replaces a value. `add` writes only when absent/expired.
`swap` performs a conditional versioned write. `touch` changes a living entry's lifetime. `drop`
removes one key. `clear` removes a space and may be expensive. `count` is an operator view, not a
constant-time assumption for request paths. Check each operation's actual return contract.

For read/modify/write, handle an absent entry before using its fields. A `swap` result of `None`
means no successful write, which can reflect contention or a store failure. Re-read/recompute only
within a bounded, justified policy. Do not silently overwrite a competing writer with `set`.
Prefer `incr` for a supported atomic counter. Its first creation starts the TTL window and later
increments do not automatically extend it. `None` is not a count and must not be treated as zero.

## Computation leases and freshness

Use `await profiles.fetch(profile_key, producer)` when concurrent cache misses would overload the
source. The producer is a callable invoked by Cachefy, not an already-created coroutine. It should
be repeat-safe and normally read/compute a value, never charge a card or send a non-idempotent message.

`ttl` bounds how long the entry lives. `stale` is the age at which it becomes eligible for refresh
within that lifetime, not an extra period automatically added after expiry. One holder refreshes
while competing callers can receive the retained stale value. A cold loser waits within the lease
bound and can compute if that bound expires. Set the lease against real producer latency and define
source I/O deadlines. A lease does not guarantee exactly-once computation after crashes or delays.
Do not assume refresh runs in an unowned background task.

A producer can fetch another key but cannot recursively wait on the same cold key it owns.
Producer exceptions propagate on a cold miss. Refresh failures over a retained stale value can
return that value and emit evidence, while invalid caller contracts remain errors. A computed value
that cannot be cached may be returned uncached with failure reporting. Check direct `set` validation
separately instead of assuming every unwritable value is silently accepted.

## Memoization and invalidation

```python
@app.cached("public-product", ttl=timedelta(minutes=5))
async def product_summary(product_id: int, locale: str) -> dict[str, str]:
    return await catalog_service.summary(product_id, locale)


summary = await product_summary(42, "en")
await product_summary.invalidate(42, "en")
```

Memo arguments are bound canonically to the signature. Use JSON-safe identifiers. For objects or
methods, supply a stable custom key that includes relevant instance/tenant identity. Do not use
Python's process-randomized `hash` or object identity as a distributed key. The wrapper is always
awaited, even around a plain function. A plain producer runs on the calling event loop, unlike a
Queuefy synchronous task handler. Explicitly offload blocking work through the application's normal
async/thread boundary. Do not create a new event loop per request around existing pooled clients.

Use `invalidate` for one memoized invocation, `refresh` to recompute deliberately, and `clear` for
its entire space. Invalidate after the authoritative write commits. Trace every writer, webhook,
admin edit, bulk import, and queue task that changes the answer. Consider the race where an older
producer finishes after invalidation. If strict freshness is required, use an actual versioned
source contract or avoid caching that path. Do not claim that deleting a key serializes database work.

## Failure semantics, lifecycle, and evidence

Store access failures are logged/reported and degrade according to the operation: reads miss,
writes can return no successful result, and `fetch` computes without a working cache. Caller errors
and startup failures remain explicit. Add hooks/metrics for misses, hit ratio, producer duration,
store failures, and invalidation effectiveness without logging values or secrets.

Use the upstream framework lifecycle integration appropriate to FastAPI/Starlette, Django, Flask,
or a standalone process. A janitor removes expired storage rather than defining whether a read is
expired. Keep sweeps bounded and lifecycle-owned. Stop owned work before closing clients.

For a tenant-specific product price, key by tenant/product/currency/locale and any actual pricing
scope. Test a cold miss, a stored `None`, a warm hit, concurrent producers, stale refresh failure,
lease expiry, source-write invalidation, Redis outage, and two tenants requesting the same product.
Verify the chosen backend, not just memory. Confirm a failed cache never bypasses authorization or
silently allows a security-sensitive quota. Deliver readable integration changes, architecture and
configuration notes, operational checks, and actual test evidence with remaining consistency limits.
Files in this package (4)
  • LICENSE.md 1 KB
  • SKILL.md 10 KB
  • references/integration.md 2 KB
  • references/sources.md 2 KB

Versions

The database has no other skills named cachefy.

Database snapshot: 13.11.2026 · package version c090314a0acc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100caching-strategies
    Design multi-tier caching architectures for web applications — cache-aside vs write-through vs write-behind, TTL design, cache invalidation, Redis patterns, CDN configuration, browser caching, and stampede prevention. Use when choosing a caching pattern, designing cache…
  • 90caching-strategies
    Caching patterns: cache-aside, write-through, stampede prevention, CDN headers, multi-level L1/L2/L3, cache invalidation. Use when designing caches or CDN strategy.
  • 90backend-caching
    Use this skill when the user says 'cache', 'Redis', 'Memcached', 'CDN', 'cache-aside', 'read-through', 'write-through', 'write-behind', 'cache invalidation', 'TTL', 'cache stampede', 'thundering herd', 'cache warming', 'LRU', 'LFU', 'cache hit ratio', 'cache strategy', or when…
  • 100caching
    Use when adding or debugging a cache. Covers cache placement, invalidation strategies, stampede protection, TTL selection, and the consistency you are trading away. Trigger on "add redis caching", "users are seeing stale data", "cache stampede after expiry", "should we cache…
  • 100cache-strategy
    Design and implement caching layers for APIs and web applications using Redis or Memcached. Use when you need to reduce database load, improve response times, or handle traffic spikes. Covers cache-aside, write-through, and write-behind patterns, TTL strategies, cache…
  • 100caching
    Use when adding or debugging caching in a service — choosing a cache strategy, designing TTLs, preventing stampedes, reasoning about invalidation, or configuring HTTP Cache-Control headers.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.