pycsamt.format.borehole.csvio#

Combined interval-CSV importer for PCBH 0.1.

Functions

boreholes_from_csv(path, *[, columns, ...])

Import a combined collar-and-interval CSV as a PCBH document.
pycsamt.format.borehole.csvio.boreholes_from_csv(path, *, columns=None, constants=None, strict=True, delimiter=None, document_id=None, created_by='pycsamt CSV importer', max_bytes=10485760, max_rows=250000)[source]

Import a combined collar-and-interval CSV as a PCBH document.

Parameters:

  • path (path-like) – UTF-8 CSV containing repeated collar fields and interval rows.

  • columns (dict, optional) – Explicit {canonical_field: source_header} mapping. Canonical names use dotted paths such as borehole.id and interval.from_md.

  • constants (dict, optional) – Constant canonical values, commonly crs.horizontal. Constants take precedence over mapped row values.

  • strict (bool, default=True) – Raise PCBHCSVImportError if any error is recorded. In permissive mode, invalid rows are rejected and valid rows returned.

  • delimiter ({',', ';', 't', '|'}, optional) – Explicit delimiter. If omitted, detection is restricted to this set.

  • document_id (str, optional) – PCBH document identifier. Defaults to csv:<file stem>.

  • created_by (str, default='pycsamt CSV importer') – Provenance name stored on the document.

  • max_bytes (int, default=10485760) – Maximum source size in bytes.

  • max_rows (int, default=250000) – Maximum number of data rows.

Returns:

  • document (PCBHDocument) – Valid document containing every accepted row.

  • report (ImportReport) – Source checksum, mappings, inferences, counts, and diagnostics.

Raises:

  • PCBHCSVImportError – If the file structure is unusable, no valid boreholes remain, or strict mode records an error. The exception exposes report.

  • ValueError – If a resource limit or delimiter parameter is invalid.

Return type:

tuple[PCBHDocument, ImportReport]

Notes

Missing tokens are normalized before conversion and never stringified. Repeated collar and total-depth values must agree within a borehole.