Caching

Caching Strategy

COT data updates only once per week, so caching API responses eliminates redundant network traffic. The SDK ships two cache backends; both honor a TTL (time-to-live) in seconds. A TTL of 24 hours (the default) is recommended.

Enabling caching

from cftc_cot import COTClient

# In-memory cache (lives for the life of the process, no dependencies)
client = COTClient(cache="memory")

# Persistent disk cache (survives restarts; requires the 'cache' extra)
client = COTClient(cache="disk", cache_dir="./cot_cache", cache_ttl=86400)

COTClient builds the cache once and threads it into every query it creates, so client.latest(...), client.history(...), the factory methods, and .execute() / .count() are all cached.

Parameters

Parameter	Default	Description
cache	None	"memory", "disk", a custom COTCache instance, or None (disabled).
cache_dir	"./cot_cache"	Directory for the disk backend.
cache_ttl	86400 (24h)	Seconds before a cached entry expires.

Disk caching dependency

Disk caching uses the optional diskcache package, installed via the cache extra:

pip install cftc-cot-soda[cache]

If cache="disk" is requested without diskcache installed, a COTError is raised with installation guidance.

Backends

• MemoryCache — a stdlib dict with per-entry expiry. No persistence, no dependencies.
• DiskCache — a thin wrapper over diskcache.Cache, persisting between runs.

Both implement the runtime-checkable COTCache protocol (get(key), set(key, value, ttl)), so you can pass your own backend:

from cftc_cot import COTClient, MemoryCache

client = COTClient(cache=MemoryCache())

How keys are computed

Each request is keyed by a SHA1 hash of the dataset id plus the resolved query parameters (select, where, order, limit, offset). Identical queries hit the cache; any change to the query produces a new key.