Python Client API Reference

Complete class and method reference for the cachecore Python package.

pip install cachecore-python

from cachecore import CachecoreClient, CachecoreTransport, CacheStatus, Dep, InvalidateResult
from cachecore.errors import CachecoreError, CachecoreAuthError, CachecoreRateLimitError

CachecoreClient

The primary interface. Manages the httpx transport, per-request context, and invalidation calls.

CachecoreClient(
    gateway_url: str,
    tenant_jwt: str,
    *,
    timeout: float = 30.0,
    debug: bool = False,
)

Parameter	Type	Default	Description
`gateway_url`	`str`	required	Cachecore gateway URL, e.g. `"https://api.cachecore.it"`
`tenant_jwt`	`str`	required	Your Cachecore JWT token (`cc_live_xxxxx.eyJ...`)
`timeout`	`float`	30.0	HTTP timeout in seconds for management API calls
`debug`	`bool`	False	Enable per-request debug logging

.transport

Returns the CachecoreTransport instance for injection into an httpx client:

import httpx
from openai import AsyncOpenAI

cc = CachecoreClient(gateway_url="...", tenant_jwt="...")
openai = AsyncOpenAI(
    http_client=httpx.AsyncClient(transport=cc.transport)
)

.request_context(deps=None, bypass=False)

Context manager that sets per-request options. Settings apply to all requests within the with block.

with cc.request_context(deps=[Dep("doc:contract-123")], bypass=False):
    response = await openai.chat.completions.create(...)

Parameter	Type	Default	Description
`deps`	`list[Dep] \| None`	None	Dependency declarations to tag this request (sent as `X-Cachecore-Deps`)
`bypass`	`bool`	False	If True, omits `X-Cachecore-Token` to trigger gateway bypass mode

await .invalidate(dep_id, new_hash=None)

Invalidate all cache entries tagged with dep_id. Returns InvalidateResult.

result = await cc.invalidate("doc:contract-123", new_hash="v2")

Parameter	Type	Default	Description
`dep_id`	`str`	required	Dependency identifier to invalidate
`new_hash`	`str \| None`	None	New hash value. Random UUID if not provided

await .invalidate_many(dep_ids, new_hash=None)

Concurrently invalidate multiple dependencies. Returns list[InvalidateResult].

await .aclose()

Close underlying HTTP clients. Called automatically when using the async context manager:

async with CachecoreClient(gateway_url="...", tenant_jwt="...") as cc:
    ...

Dep

Declares a data dependency for cache tagging. Alias for DepDeclaration.

Dep(dep_id: str, hash: str = "v1")

Attribute	Type	Description
`.dep_id`	`str`	Dependency identifier
`.expected_hash`	`str`	Expected version hash

Dep("table:products")                    # hash defaults to "v1"
Dep("doc:contract-123", hash="abc123")   # explicit version

CacheStatus

Parsed cache metadata from response headers. Frozen dataclass. Read from X-Cache, X-Cache-Similarity, and X-Cache-Age response headers.

CacheStatus(
    status: Literal["HIT_L1", "HIT_L1_STALE", "HIT_L2", "MISS", "BYPASS", "UNKNOWN"],
    similarity: float,   # 0.0-1.0
    age_seconds: int,    # 0 for MISS/BYPASS
)

CacheStatus.from_headers(headers)

Parse from an httpx Headers object:

status = CacheStatus.from_headers(httpx_response.headers)

InvalidateResult

Result of a single invalidation operation. Frozen dataclass.

Field	Type	Description
`dep_id`	`str`	The dependency that was invalidated
`ok`	`bool`	Whether the operation succeeded
`error`	`str \| None`	Error message if failed

Exceptions

Exception	Trigger	Notes
`CachecoreError`	Base class	All Cachecore exceptions inherit from this
`CachecoreAuthError`	401 or 403 from gateway	Invalid or expired JWT
`CachecoreRateLimitError`	429 from gateway	Has `.retry_after: float \| None` attribute

CachecoreTransport

Low-level httpx transport. Typically accessed via cc.transport rather than constructed directly.

CachecoreTransport(
    jwt: str,
    *,
    wrapped: httpx.AsyncBaseTransport | None = None,
    debug: bool = False,
)

Extends httpx.AsyncBaseTransport. On each request, injects:

X-Cachecore-Token: the JWT (unless bypass is active)
X-Cachecore-Deps: base64url-encoded dependency array (if deps declared in current context)