bdf.read

bdf.read(path: str | Path, *, plugin: Plugin | str | None = None, normalize: bool = True, validate: bool = True, include_unknown: bool = False, tz: str = 'UTC', reconcile_time: bool = False) → tuple[DataFrame, dict]

Read path (local file or URL) to BDF-canonical form, returning (df, metadata).

Collects to a polars.DataFrame; use scan() for a polars.LazyFrame.

Parameters:

• path – Local file path or http(s) URL to read.

• plugin – Plugin instance or registry id. Auto-detects if not set (default).

• normalize – Map vendor columns to BDF canonical names (default True); False returns raw source columns unchanged.

• validate – Check columns against the BDF ontology, error if missing required columns (default True); set to False to only warn.

• include_unknown – Keep columns outside of the BDF spec in the dataframe (default False).

• tz – IANA timezone used to compute Unix Time / s if the source has naive datetime. Default is``”UTC”``, and will warn if source contains naive datetimes.

• reconcile_time – Elapsed-time columns are cross-checked against wall-clock increments when both are present (e.g. a vendor export storing milliseconds under a seconds header, GH #65). A mismatch raises BDFValidationError by default (warns when validate=False); pass reconcile_time=True to explicitly rescale known unit factors, recorded under metadata["time_reconciliation"]. Only active when normalize=True.

Returns:

the BDF table as a DataFrame, and a metadata dict with at least a "source" key naming the resolved plugin id ("custom" for a directly-supplied Plugin).

Return type:

Tuple of (df, metadata)

Raises:

ValueError – If plugin is not None, a str, or a Plugin instance.