Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

cachefy

/cachefy

Projektuje i wdraża asynchroniczne cache w Pythonie: przestrzenie, unieważnianie, kontrolę stampede i wybór backendu.

Repozytorium
skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
09.11.2026

Ocena i bezpieczeństwo

95/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść30 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 09.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Projektuje i wdraża asynchroniczne cache w Pythonie: przestrzenie, unieważnianie, kontrolę stampede i wybór backendu.

Oryginalny opis (EN)

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.

Jak działa

  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
Sekcje z nagłówków SKILL.md, w oryginale · 167 linii, 1 376 słów
Podgląd SKILL.md
---
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.
Pliki w paczce (4)
  • LICENSE.md 1 KB
  • SKILL.md 10 KB
  • references/integration.md 2 KB
  • references/sources.md 2 KB

Wersje

W bazie nie ma innych skilli o nazwie cachefy.

Migawka bazy z 13.11.2026 · wersja paczki c090314a0acc (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100caching-strategies
    Projektuje wielowarstwowe architektury cache dla aplikacji webowych: wzorce cache-aside i write-through, TTL, unieważnianie, Redis, CDN, nagłówki Cache-Control i ochrona przed stampede.
  • 90caching-strategies
    Podpowiada wzorce cache: cache-aside, write-through, zapobieganie stampede, nagłówki CDN, poziomy L1, L2 i L3 oraz unieważnianie.
  • 90backend-caching
    Projektuje warstwę cache: wzorce odczytu i zapisu, unieważnianie, zapobieganie lawinie żądań, TTL i monitoring trafień.
  • 100caching
    Pomaga dodać lub zdiagnozować cache: umiejscowienie, unieważnianie, ochrona przed stampede, dobór TTL i świadomość kompromisu w spójności danych.
  • 100cache-strategy
    Projektuje i wdraża warstwy cache dla API i aplikacji webowych w Redis lub Memcached: cache-aside, write-through, write-behind, TTL, unieważnianie i ochrona przed stampede.
  • 100caching
    Pomaga dodawać i debugować cache w usłudze: dobór strategii, projektowanie TTL, ochrona przed stampede, unieważnianie oraz konfiguracja nagłówków HTTP Cache-Control.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.