cacheow

Development-only caching and mocking for expensive Python functions. Add one decorator, then control runtime behavior through persisted disk storage and a small web UI.

Development use only. Do not use cacheow in production. When disabled, the decorator is a no-op with near-zero overhead.

Requirements

• Python 3.13+

Installation

pip install cacheow

Quick start

Enable cacheow with an environment variable:

export CACHEOW_ENABLE=1

from cacheow import cacheow

@cacheow()
def expensive_function(x: int) -> int:
    return x * x

expensive_function(3)  # recorded to disk in default mode

When CACHEOW_ENABLE is not 1, @cacheow() returns the original function unchanged.

A control panel starts automatically at http://127.0.0.1:8765/ (configurable via environment variables below).

Runtime modes

Each decorated function has one mode, persisted in SQLite:

Always set mode using function.cacheow_function_id on the wrapped function. Do not look up functions by name in SQLite; stale registrations can remain after source edits.

Modes can also be changed via the web UI or JSON API (see below).

Complete example

Save as cacheow_example.py and run with python cacheow_example.py:

import asyncio
import os
import time

os.environ.setdefault("CACHEOW_ENABLE", "1")
os.environ.setdefault("CACHEOW_DATA_DIR", ".cacheow")
os.environ.setdefault("CACHEOW_START_SERVER", "1")

from cacheow import cacheow
from cacheow.manager import get_manager


@cacheow()
def sync_compute(n: int) -> int:
    print(f"computing {n}")
    time.sleep(0.1)
    return n * n


@cacheow()
async def async_compute(n: int) -> int:
    print(f"async computing {n}")
    await asyncio.sleep(0.1)
    return n + 10


def main() -> None:
    print("=== Default mode: record outcomes ===")
    print("sync_compute(3) =", sync_compute(3))
    print("async_compute(5) =", asyncio.run(async_compute(5)))

    manager = get_manager()
    assert manager is not None
    fn_id: str = sync_compute.cacheow_function_id  # type: ignore[attr-defined]

    print("\n=== Cache mode: replay from disk ===")
    manager.db.set_mode(fn_id, "cache")
    start = time.perf_counter()
    print(
        "sync_compute(3) cached =",
        sync_compute(3),
        f"in {(time.perf_counter() - start) * 1000:.1f}ms",
    )

    print("\n=== Mock mode: never call original ===")
    manager.db.set_mode(fn_id, "mock")
    print("sync_compute(999) mocked =", sync_compute(999))

    host = manager.settings.server_host
    port = manager.settings.server_port
    print(f"\nControl panel: http://{host}:{port}/")
    print(f"Data directory: {manager.settings.data_dir}")


if __name__ == "__main__":
    main()

Expected output (approximate):

=== Default mode: record outcomes ===
computing 3
sync_compute(3) = 9
async computing 5
async_compute(5) = 15

=== Cache mode: replay from disk ===
sync_compute(3) cached = 9 in 0.5ms

=== Mock mode: never call original ===
sync_compute(999) mocked = 9

Control panel: http://127.0.0.1:8765/
Data directory: /path/to/.cacheow

In cache and mock modes, computing ... is not printed — the original function is not called.

Environment variables

Supported function types

• Sync and async functions
• Sync and async generators
• Functions that raise exceptions
• Arbitrary return types (JSON-first serialization with pickle fallback)

On-disk layout

.cacheow/
  cacheow.db              # SQLite: metadata, modes, stats, outcome index
  functions/
    <function-id>/
      outcomes/
        <outcome-id>.json # Human-inspectable outcome payloads

SQLite stores registration, modes, configuration, stats, and an index of outcome files. JSON files store the actual return values, exceptions, and generator sequences so outcomes stay easy to inspect, diff, and edit manually.

HTTP API

HTML UI: / and /ui/functions/{id}.

Safety

In default mode, persistence or stats failures log a warning and never prevent the wrapped function from returning its result. In cache mode, cache read failures fall back to executing the original function when safe.

Public API

from cacheow import cacheow

That is the intended user-facing entry point. Wrapped functions expose cacheow_function_id for runtime control.