2.23.7.5. pycsamt.format.borehole.xlsxio#

Spreadsheet (.xlsx) importer for PCBH 0.1.

Field borehole logs almost never arrive in the tidy one-interval-per-row shape that pycsamt.format.borehole.boreholes_from_csv() expects: a typical workbook has a multi-row merged header, a Rock name column, a From/To depth pair, bilingual labels, and no collar coordinates at all. This module turns such a sheet into a canonical PCBHDocument by

  1. flattening one chosen sheet to a header row + value rows,

  2. resolving canonical PCBH fields from that header (the same alias machinery as the CSV importer, plus spreadsheet-specific hints),

  3. injecting an external collar position (per hole, or one shared collar) supplied out-of-band, and

  4. delegating to pycsamt.format.borehole.csvio.assemble_interval_document().

No pandas dependency: openpyxl is imported lazily, read-only.

Functions

boreholes_from_xlsx(source, *[, sheet, ...])

Import one worksheet of a borehole workbook as a PCBH document.

inspect_workbook(source)

Return sheet names, shapes, previews, and header-row guesses.

sheet_rows(source, *[, sheet, header_row])

Flatten one worksheet to (sheet_name, headers, data_rows).

Classes

SheetOutline(name, n_rows, n_cols[, ...])

Lightweight description of one worksheet.

WorkbookOutline(source[, sheets])

All sheets in a workbook, previews only — no bulk data read.
class pycsamt.format.borehole.xlsxio.SheetOutline(name, n_rows, n_cols, preview=<factory>, header_candidates=<factory>)[source]

Bases: PyCSAMTObject

Lightweight description of one worksheet.

Parameters:
name: str
n_rows: int
n_cols: int
preview: list[list[str]]
header_candidates: list[int]
class pycsamt.format.borehole.xlsxio.WorkbookOutline(source, sheets=<factory>)[source]

Bases: PyCSAMTObject

All sheets in a workbook, previews only — no bulk data read.

Parameters:

  • source (str)

  • sheets (list[SheetOutline])

source: str
sheets: list[SheetOutline]
sheet(key)[source]

Return one sheet by name or positional index.

Parameters:

key (str | int)

Return type:

SheetOutline

pycsamt.format.borehole.xlsxio.inspect_workbook(source)[source]

Return sheet names, shapes, previews, and header-row guesses.

Parameters:

source (path-like or bytes) – An .xlsx workbook. Bytes are accepted so an application can pass an uploaded payload without touching disk.

Returns:

One SheetOutline per worksheet.

Return type:

WorkbookOutline

pycsamt.format.borehole.xlsxio.boreholes_from_xlsx(source, *, sheet=None, header_row=None, columns=None, constants=None, collars=None, default_borehole_id=None, strict=True, document_id=None, created_by='pycsamt XLSX importer', max_bytes=10485760, max_rows=250000)[source]

Import one worksheet of a borehole workbook as a PCBH document.

Parameters:

  • source (path-like or bytes) – The .xlsx workbook.

  • sheet (str or int, optional) – Worksheet name or 0-based index. Defaults to the first sheet.

  • header_row (int, optional) – 0-based row index of the header. Auto-detected when omitted (the first row with at least two text cells).

  • columns (dict, optional) – Explicit {canonical_field: source} mapping. source may be a header string, a 0-based column index, or an Excel column letter. Canonical names use dotted paths such as interval.from_md.

  • constants (dict, optional) – Constant canonical values (commonly borehole.id and crs.horizontal for a single-hole sheet).

  • collars (dict or path-like, optional) – External collar positions, keyed by borehole id ({"ZK2203": {"x": .., "y": .., "z": .., "crs": "EPSG:32648"}}), or a single {"x": .., "y": .., "z": ..} applied to every hole, or a small CSV with id,x,y,z[,crs] columns. Spreadsheets rarely carry coordinates, so this is how they enter the document.

  • strict (bool, default=True) – Raise PCBHCSVImportError on any recorded error. In permissive mode a missing collar/CRS becomes a flagged placeholder and invalid rows are dropped.

  • document_id (str, optional) – Defaults to xlsx:<file stem>.

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

  • max_bytes (int) – Resource limits, shared with the CSV importer.

  • max_rows (int) – Resource limits, shared with the CSV importer.

  • default_borehole_id (str | None)

Returns:

  • document (PCBHDocument)

  • report (ImportReport) – Includes the resolved sheet, header row, column mapping, injected collars, and every rejected row.

Return type:

tuple[PCBHDocument, ImportReport]

pycsamt.format.borehole.xlsxio.sheet_rows(source, *, sheet=None, header_row=None)[source]

Flatten one worksheet to (sheet_name, headers, data_rows).

A thin public wrapper around the workbook flattening used by boreholes_from_xlsx(), for callers that resolve their own canonical fields (e.g. pycsamt.format.pointset). header_row is 0-based; auto-detected when omitted.

Parameters:
Return type:

tuple[str, list[str], list[list[str]]]