tsdive.write_tag ¶

write_tag(
    path: str | Path,
    frame: DataFrame,
    meta: TagMeta,
    *,
    overwrite: bool = False,
) -> Path

Create a single-tag parquet archive at path and return it.

This is an archive creation call, not an edit. Ingested archives stay read-only: nothing here rewrites, appends to, or patches an existing file, and an existing path raises FileExistsError unless overwrite=True, which replaces the whole archive rather than changing part of it.

frame must carry timestamp (UTC-aware), value and quality; validate_schema refuses anything else, so a quality-free archive cannot be created by accident. meta is embedded under the tsdive.meta key, which is what makes the file readable by TagStore at all.

Examples:

>>> import pandas as pd
>>> import tsdive
>>> frame = pd.DataFrame({
...     "timestamp": pd.date_range("2024-03-30 20:00", periods=3, freq="min", tz="UTC"),
...     "value": [62.0, 62.1, 62.3],
...     "quality": ["GOOD", "GOOD", "GOOD"],
... })
>>> meta = tsdive.TagMeta(identity=tsdive.TagIdentity("plant1", "FI102.PV"),
...                       name="FI-102 flow", sample_rate_s=60.0)
>>> path = tsdive.write_tag("archive/plant1/FI102.PV.parquet", frame, meta)
>>> path.as_posix()
'archive/plant1/FI102.PV.parquet'
>>> tsdive.write_tag(path, frame, meta)
Traceback (most recent call last):
...
FileExistsError: ...