Skip to content

cachier integration: sync and asyncio

cachier stores a function's return value so repeated calls with the same arguments avoid repeating the calculation. client-query-cache caches MongoDB reads, so looking up that stored return value can also avoid a database round trip.

These programs calculate a sales report from MongoDB orders. The first call adds up sales for the North region; subsequent calls reuse cachier's stored report. A small collection adapter connects the two libraries through cachier's public mongetter argument. Its find_one uses a retained cached collection; writes, deletion, and index operations use the original PyMongo collection. cachier keeps control of its lookup filters and serialization.

Each program reuses one client, process-local manager, and adapter. The asyncio version uses AsyncMongoClient, the asynchronous manager, an async mongetter, and await report.aclear_cache(). Each manager closes before its client. See manager selection for other deployment choices.

Run either program

Use a repository checkout on a supported Python and platform configuration, with uv available. MongoDB must meet the same requirements, including a replica set or sharded cluster. Follow Local MongoDB to start the repository's disposable replica set.

Run from the repository root, without editing the source:

uv run examples/cachier_example.py
uv run examples/cachier_async_example.py

Each script declares cachier[mongo]>=4.2.0 and uses the working-tree client-query-cache package. uv resolves the published cachier package into a separate script environment; no local cachier checkout is needed.

MONGODB_URI selects the server and defaults to mongodb://localhost:27017/?directConnection=true. Set it in your environment to use another disposable deployment.

Disposable databases: Every run resets its entire dedicated database: client_query_cache_example_cachier for sync, or client_query_cache_example_cachier_async for asyncio. Do not keep valuable data in these databases.

What to expect

The programs check their values and fail with an explicit message if cache warm-up or invalidation exceeds ten seconds. Successful output includes:

initial North sales: EUR 200
repeated calls: 1 calculation, <positive count> query-cache hits
updated North sales: EUR 220; calculations: 2
invalidation observed after: <elapsed> ms

The hit count and elapsed time vary. Repeated calls reuse one calculation and produce MongoDB query-cache hits. The program then changes an order from EUR 80 to EUR 100. Changing source orders alone does not expire the stored report: cachier controls function-result expiry and clearing. Clearing removes the stored report, and the program waits until a call recalculates the EUR 220 total.

Clearing does not guarantee immediate freshness. A process-local lookup may return the previous report until change-stream invalidation arrives. See consistency limits before adapting this pattern to an application that requires fresh reads.

Use this pattern for calculations that tolerate stale reads and are safe to repeat without unwanted side effects (idempotent calculations). The adapter also caches cachier's calculation status. With independent managers, stale status can cause duplicate calculations or, in the synchronous path, unnecessary waiting. Do not rely on it for strict coordination between workers. In cachier 4.2.0, synchronous calls can wait for an ongoing calculation; asyncio calls recalculate rather than use that wait path, and do not honor wait_for_calc_timeout. These programs check sequential calls only.

The demonstrated benefit comes from repeated reads between storage writes. cachier's default lookup index is non-unique, so a write to any stored result in the same collection invalidates these cached lookups, including unrelated reports. Frequent storage writes can therefore reduce query-cache reuse. See single-document reads for the library's invalidation rules.

Trust cache writers: cachier's MongoDB storage serializes return values with pickle. Only trusted writers should have access to that storage; loading a malicious pickle can execute code.

Complete synchronous program

The code is included from the canonical Python source.

# /// script
# requires-python = ">=3.14"
# dependencies = ["client-query-cache", "cachier[mongo]>=4.2.0"]
#
# [tool.uv.sources]
# client-query-cache = { path = "..", editable = true }
# ///

import os
from time import monotonic, sleep
from typing import Any

from cachier import cachier
from pymongo import MongoClient

from client_query_cache import CacheCoreConfig, CacheManager
from client_query_cache._types import NonNegativeInt

DATABASE_NAME = "client_query_cache_example_cachier"
DEFAULT_MONGODB_URI = "mongodb://localhost:27017/?directConnection=true"
WAIT_TIMEOUT_SECONDS = 10.0


class CachedCollection:
    """Cache storage reads and retain PyMongo's write and index operations."""

    def __init__(self, manager: CacheManager[dict[str, Any]]) -> None:
        collection = manager.client[DATABASE_NAME]["function_results"]
        self.cached_collection = manager.get_cached_collection(collection)
        self.find_one = self.cached_collection.find_one
        self.update_one = collection.update_one
        self.update_many = collection.update_many
        self.delete_many = collection.delete_many
        self.index_information = collection.index_information
        self.create_indexes = collection.create_indexes


def run_scenario(manager: CacheManager[dict[str, Any]]) -> None:
    orders = manager.client[DATABASE_NAME]["orders"]
    orders.insert_many(
        (
            {"_id": "order-1", "region": "North", "amount_eur": 120},
            {"_id": "order-2", "region": "North", "amount_eur": 80},
            {"_id": "order-3", "region": "South", "amount_eur": 50},
        )
    )
    adapter = CachedCollection(manager)

    def mongetter() -> CachedCollection:
        return adapter

    calculations: NonNegativeInt = 0

    # cachier's decorator has no return annotation and types mongetter as a
    # concrete Collection. This adapter supplies the required collection methods.
    @cachier(backend="mongo", mongetter=mongetter)  # type: ignore[arg-type, untyped-decorator]
    def report(region: str) -> NonNegativeInt:
        nonlocal calculations
        calculations += 1
        totals = tuple(
            orders.aggregate(
                [
                    {"$match": {"region": region}},
                    {"$group": {"_id": None, "sales_eur": {"$sum": "$amount_eur"}}},
                ]
            )
        )
        return totals[0]["sales_eur"] if totals else 0

    if report("North") != 200:
        raise SystemExit("initial North sales report should total EUR 200")
    print("initial North sales: EUR 200")

    # Wait for storage writes to settle and for repeated lookups to hit the cache.
    hits_before = manager.snapshot().hits
    started = monotonic()
    while True:
        for _ in range(5):
            if report("North") != 200 or calculations != 1:
                raise SystemExit("repeated calls must reuse one EUR 200 calculation")
        cache_hits = manager.snapshot().hits - hits_before
        if cache_hits > 0:
            break
        if monotonic() - started >= WAIT_TIMEOUT_SECONDS:
            raise SystemExit("cache warm-up timed out: no query-cache hits")
        sleep(0.05)
    print(f"repeated calls: {calculations} calculation, {cache_hits} query-cache hits")

    orders.update_one({"_id": "order-2"}, {"$set": {"amount_eur": 100}})
    if report("North") != 200 or calculations != 1:
        raise SystemExit("changing orders alone should preserve the stored report")

    report.clear_cache()
    started = monotonic()
    while report("North") != 220:
        if monotonic() - started >= WAIT_TIMEOUT_SECONDS:
            raise SystemExit("invalidation timed out: cleared report is still stale")
        sleep(0.05)
    if calculations != 2:
        raise SystemExit("clearing should cause exactly one new calculation")
    print("updated North sales: EUR 220; calculations: 2")
    print(f"invalidation observed after: {(monotonic() - started) * 1000:.0f} ms")


def main() -> None:
    mongodb_uri = os.getenv("MONGODB_URI", DEFAULT_MONGODB_URI)
    with MongoClient[dict[str, Any]](mongodb_uri) as client:
        client.drop_database(DATABASE_NAME)
        client[DATABASE_NAME].create_collection("function_results")
        with CacheManager(
            client, cache_config=CacheCoreConfig(enable_telemetry=True)
        ) as manager:
            run_scenario(manager)


if __name__ == "__main__":
    main()

Complete asyncio program

The code is included from the canonical Python source.

# /// script
# requires-python = ">=3.14"
# dependencies = ["client-query-cache", "cachier[mongo]>=4.2.0"]
#
# [tool.uv.sources]
# client-query-cache = { path = "..", editable = true }
# ///

import asyncio
import os
from time import monotonic
from typing import Any

from cachier import cachier
from pymongo import AsyncMongoClient

from client_query_cache import CacheCoreConfig
from client_query_cache._types import NonNegativeInt
from client_query_cache.asynchronous import CacheManager

DATABASE_NAME = "client_query_cache_example_cachier_async"
DEFAULT_MONGODB_URI = "mongodb://localhost:27017/?directConnection=true"
WAIT_TIMEOUT_SECONDS = 10.0


class CachedCollection:
    """Cache storage reads and retain PyMongo's write and index operations."""

    def __init__(self, manager: CacheManager[dict[str, Any]]) -> None:
        collection = manager.client[DATABASE_NAME]["function_results"]
        self.cached_collection = manager.get_cached_collection(collection)
        self.find_one = self.cached_collection.find_one
        self.update_one = collection.update_one
        self.update_many = collection.update_many
        self.delete_many = collection.delete_many
        self.index_information = collection.index_information
        self.create_indexes = collection.create_indexes


async def run_scenario(manager: CacheManager[dict[str, Any]]) -> None:
    orders = manager.client[DATABASE_NAME]["orders"]
    await orders.insert_many(
        (
            {"_id": "order-1", "region": "North", "amount_eur": 120},
            {"_id": "order-2", "region": "North", "amount_eur": 80},
            {"_id": "order-3", "region": "South", "amount_eur": 50},
        )
    )
    adapter = CachedCollection(manager)

    async def mongetter() -> CachedCollection:  # noqa: RUF029 -- cachier requires an async mongetter
        return adapter

    calculations: NonNegativeInt = 0

    # cachier's decorator has no return annotation and types mongetter as a
    # concrete Collection. This adapter supplies the required collection methods.
    @cachier(backend="mongo", mongetter=mongetter)  # type: ignore[arg-type, untyped-decorator]
    async def report(region: str) -> NonNegativeInt:
        nonlocal calculations
        calculations += 1
        cursor = await orders.aggregate(
            [
                {"$match": {"region": region}},
                {"$group": {"_id": None, "sales_eur": {"$sum": "$amount_eur"}}},
            ]
        )
        totals = await cursor.to_list()
        return totals[0]["sales_eur"] if totals else 0

    if await report("North") != 200:
        raise SystemExit("initial North sales report should total EUR 200")
    print("initial North sales: EUR 200")

    # Wait for storage writes to settle and for repeated lookups to hit the cache.
    hits_before = manager.snapshot().hits
    started = monotonic()
    while True:
        for _ in range(5):
            if await report("North") != 200 or calculations != 1:
                raise SystemExit("repeated calls must reuse one EUR 200 calculation")
        cache_hits = manager.snapshot().hits - hits_before
        if cache_hits > 0:
            break
        if monotonic() - started >= WAIT_TIMEOUT_SECONDS:
            raise SystemExit("cache warm-up timed out: no query-cache hits")
        await asyncio.sleep(0.05)
    print(f"repeated calls: {calculations} calculation, {cache_hits} query-cache hits")

    await orders.update_one({"_id": "order-2"}, {"$set": {"amount_eur": 100}})
    if await report("North") != 200 or calculations != 1:
        raise SystemExit("changing orders alone should preserve the stored report")

    await report.aclear_cache()
    started = monotonic()
    while await report("North") != 220:
        if monotonic() - started >= WAIT_TIMEOUT_SECONDS:
            raise SystemExit("invalidation timed out: cleared report is still stale")
        await asyncio.sleep(0.05)
    if calculations != 2:
        raise SystemExit("clearing should cause exactly one new calculation")
    print("updated North sales: EUR 220; calculations: 2")
    print(f"invalidation observed after: {(monotonic() - started) * 1000:.0f} ms")


async def main() -> None:
    mongodb_uri = os.getenv("MONGODB_URI", DEFAULT_MONGODB_URI)
    async with AsyncMongoClient[dict[str, Any]](mongodb_uri) as client:
        await client.drop_database(DATABASE_NAME)
        await client[DATABASE_NAME].create_collection("function_results")
        async with CacheManager(
            client, cache_config=CacheCoreConfig(enable_telemetry=True)
        ) as manager:
            await run_scenario(manager)


if __name__ == "__main__":
    asyncio.run(main())