API reference / Archive, sampling contract and types
TagStore(root: Path)
Read-only view over root/<source_id>/<point_id>.parquet files.
Methods:
| Name | Description |
|---|---|
archive_path |
The path |
list_tags |
One identity per |
read_window |
Return a window plus its data-physics block. |
Attributes:
| Name | Type | Description |
|---|---|---|
root |
|
archive_path(identity: TagIdentity) -> Path
The path root/<source_id>/<point_id>.parquet of identity, existing or not.
Examples:
>>> import tsdive
>>> store = tsdive.TagStore("data")
>>> store.archive_path(tsdive.TagIdentity("demo", "fic101_demo")).as_posix()
'data/demo/fic101_demo.parquet'
list_tags() -> list[TagIdentity]
One identity per root/<source_id>/<point_id>.parquet file, sorted.
The identity is read off the path, not off the file's tsdive.meta.
Examples:
>>> import tsdive
>>> store = tsdive.TagStore("data")
>>> [str(tag) for tag in store.list_tags()][:2]
['demo:fic101_demo', 'demo:tic101_demo']
read_window(
identity: TagIdentity,
start: datetime,
end: datetime,
contract: SamplingContract,
*,
min_severity: Severity = Severity.GOOD,
tz_names: tuple[str, ...] = (),
) -> Window
Return a window plus its data-physics block.
contract is a required positional argument: every read states
how its numbers were produced.
Coverage accounts for the whole requested span, not just the part
between the first and last sample: the interval from start to
the first sample and from the last sample to end are classified
by the same gap rules and count toward n_gaps, longest_gap_s
and coverage. A window with no samples reports coverage=0.0 and
one unknown gap spanning the window - never a fake 1.0.
When the tag's metadata declares retrieval_mode, the window's
contract carries that mode in place of the one contract states:
the export fixed how its samples were retrieved, and no read of the
archive can change it.
A window whose timestamps go backwards is refused with
NonMonotonicIndex before any physics is
computed. Gaps and coverage over a re-sorted index would describe
an ordering the historian never produced.