xj'dZddlmZddlmZddlmZddlmZm Z m Z ddl Z ddl mZmZgdZed d Gd d Ze d e j$ZddZddZy)aServer-side caching hints (SEP-2549, protocol revision 2026-07-28). Results for the cacheable methods carry `ttlMs`/`cacheScope` freshness hints. A handler sets them by returning a result with explicit `ttl_ms`/`cache_scope` values; `Server(cache_hints={method: CacheHint(...)})` fills them for handlers that don't. Fields the handler set win, per field, so a server-wide hint never overrides a handler's explicit choice. ) annotations)Mapping) dataclass)AnyLiteralTypeVarN)CACHEABLE_METHODSCacheableMethod)r CacheHintr apply_cache_hintvalidate_cache_hintsT)frozenslotsc6eZdZUdZdZded<dZded<d dZy ) r aOFreshness hint for one cacheable method's results. `ttl_ms` is how long, in milliseconds, a client may consider the result fresh (`0` means immediately stale). `scope` is whether a cached result may be shared across authorization contexts (`"public"`) or only reused within the one that produced it (`"private"`). rintttl_msprivatezLiteral['public', 'private']scopec|jdkrtd|j|jdvrtd|jy)Nrzttl_ms must be >= 0, got )publicrz)scope must be 'public' or 'private', got )r ValueErrorr)selfs f/mnt/ssd/data/Dropbox/adrian/sandbox/mcp-query/venv/lib/python3.12/site-packages/mcp/server/caching.py __post_init__zCacheHint.__post_init__#sM ;;?8 FG G ::2 2HWX X 3N)returnNone)__name__ __module__ __qualname____doc__r__annotations__rrrrr r s#FCO*3E '3Yrr CacheableResultT)boundci}d|jvr|j|d<d|jvr|j|d<|r|j|S|S)aYFill `ttl_ms`/`cache_scope` on `result` from `hint`. Per-field: a field the handler set explicitly - even to its default value, tracked via `model_fields_set` - is left alone; only unset fields take the hint. A handler constructing results with `model_construct` bypasses that tracking and is treated as having set nothing. r cache_scope)update)model_fields_setrr model_copy)resulthintr(s rr r -s\$&Fv...;;xF333 $ }/56  F  +A6Arc |iStd|D}|rtddj|i}|jD]>\}}t |t s$t d|dt|j|||<@|S)aValidate a `cache_hints` constructor argument into a plain dict. The `Server`/`MCPServer` signatures already close the key set and value type for type-checked callers; this runtime gate is deliberately loose in its parameter so it covers everyone else (e.g. a map deserialized from config) - a bad entry fails at construction, not on the first request to that method. Raises: ValueError: If a key is not a cacheable method. TypeError: If a value is not a `CacheHint`. c3DK|]}|tvs t|yw)N)r repr).0methods r z'validate_cache_hints..Ms_fvM^?^T&\_s  zGcache_hints keys must be cacheable methods (see CacheableMethod); got: z, z cache_hints[z] must be a CacheHint, got ) sortedrjoinitems isinstancer TypeErrortyper) cache_hintsunknown validatedr1r,s rr r =s _ __Gbcgclclmtcubvwxx&(I#))+! $ *l6*4OPTUYPZPcPcOdef f &! r)r+r$r,r rr$)r9zMapping[Any, Any] | Nonerzdict[str, CacheHint])r! __future__rcollections.abcr dataclassesrtypingrrr mcp_typestypesmcp_types.methodsr r __all__r CacheableResultr$r r r#rrrEsj##!((@ k $d#YY$Y&-U5J5JK B r