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', day_month_order: Literal['day_first', 'month_first'] | None = None, reconcile_time: bool = False) → tuple[DataFrame, Metadata][source]#

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.
day_month_order – Field order applied to an ambiguous numeric date the table column and the staged metadata each declare. "day_first" reads it day then month, "month_first" reads it month then day; None (default) leaves every declared format unchanged.
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.bdf.time_reconciliation. Only active when normalize=True.

Returns:

the BDF table as a DataFrame, and a Metadata carrying the five entity records, bdf (with at least source naming the resolved plugin id, "custom" for a directly-supplied Plugin), raw, and extras.

Return type:

Tuple of (df, metadata)

Raises:

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