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)