cosmodol.stores

Mapping stores over a Cosmos DB container.

Two store flavors — pick one based on whether you have a fixed partition key value or want to span the whole container:

• CosmosItems — fixed partition; keys are id strings; the simplest dict surface.

• CosmosPartitionedItems — whole container; keys are (pk_value, id) tuples.

See misc/docs/architecture.md Layer B and misc/docs/design_decisions.md §3.

class cosmodol.stores.CosmosItems(container: ContainerProxy | dict | tuple, *, partition_key_value: Any, partition_key_path: str | None = None, connection: Any = None, inject_id: bool = True, inject_partition_key: bool = True, strict_keys: bool = True, strip_system_fields: bool = True, record_ru: Callable[[str, float], None] | None = None)

MutableMapping[str, dict] over one fixed partition of a Cosmos container.

Keys are item id strings; values are JSON-dict items. The store auto-injects id and the partition-key property on writes.

Parameters:

• container – An already-built ContainerProxy or a (database, container) tuple / {"database": ..., "container": ...} dict to resolve via connection.

• partition_key_value – The single partition-key value this store is scoped to.

• partition_key_path – Path of the partition-key property in items (e.g. "/_pk", "/id"). Read from the container if absent.

• connection – CosmosConnection (or anything from_anything accepts). Ignored if container is a ContainerProxy.

• inject_id – If True, auto-inject "id" into bodies on writes.

• inject_partition_key – If True, auto-inject the partition-key property into bodies.

• strict_keys – Validate id chars + length on writes.

• strip_system_fields – Strip _etag/_ts/_rid/_self/_attachments from returned items.

• record_ru – Optional callback (op_name, ru) -> None invoked after each metal-layer op. Useful for Prometheus / logging.

batch(operations: list[tuple]) → list[dict]

Transactional batch within this partition. See base.batch.

query(sql: str, *, parameters: list[dict] | None = None) → Iterator[dict]

Run a SQL query scoped to this partition. Yields raw item dicts (no stripping).

replace(k: str, v: dict, *, etag: str | None = None) → dict

Full replace with optional ETag-conditional write.

class cosmodol.stores.CosmosPartitionedItems(container: ContainerProxy | dict | tuple, *, partition_key_path: str | None = None, connection: Any = None, inject_id: bool = True, inject_partition_key: bool = True, strict_keys: bool = True, strip_system_fields: bool = True, record_ru: Callable[[str, float], None] | None = None, len_via_query: bool = False, silent_full_scan: bool = False)

MutableMapping[tuple[str, str], dict] over all partitions of a container.

Keys are (partition_key_value, id) tuples. Use CosmosItems instead if you have a fixed partition.

Iteration is cross-partition; the first call emits a UserWarning (silence with silent_full_scan=True). __len__ is not implemented by default; opt-in via len_via_query=True. See misc/docs/design_decisions.md §§4, 6.

Parameters:

• container – As in CosmosItems.

• partition_key_path – Path of the partition-key property in items. Read from the container if absent.

• connection – As in CosmosItems.

• inject_id – As in CosmosItems.

• inject_partition_key – As in CosmosItems.

• strict_keys – As in CosmosItems.

• strip_system_fields – As in CosmosItems.

• record_ru – As in CosmosItems.

• len_via_query – If True, __len__ runs a (cross-partition) COUNT query.

• silent_full_scan – If True, __iter__ does not emit the cross-partition warning.

partition(pk_value) → CosmosItems

Narrow to a single partition; zero round-trips. Returns CosmosItems.

query(sql: str, *, parameters: list[dict] | None = None, partition_key: Any = None, cross_partition: bool = False) → Iterator[dict]

Pass-through to base.query.