pycsamt.format.borehole.jsonio#

Canonical UTF-8 JSON reader and writer for PCBH 0.1.

Functions

pcbh_from_dict(value, *[, validate, ...])

Build a PCBH document from a decoded JSON mapping.

pcbh_to_dict(document, *[, validate])

Convert a PCBH document to its canonical JSON-compatible mapping.

read_pcbh(path, *[, validate, max_bytes, ...])

Read a canonical PCBH JSON file.

write_pcbh(document, path, *[, validate, indent])

Atomically write a canonical PCBH JSON file.
pycsamt.format.borehole.jsonio.pcbh_to_dict(document, *, validate=True)[source]

Convert a PCBH document to its canonical JSON-compatible mapping.

Parameters:

  • document (PCBHDocument) – In-memory document to convert.

  • validate (bool, default True) – Run semantic validation before conversion.

Returns:

Canonically ordered JSON-compatible mapping.

Return type:

dict

Raises:

  • TypeError – If document is not a PCBHDocument.

  • PCBHValidationError – If semantic validation fails.

  • ValueError – If metadata or extension values are not finite JSON values.

pycsamt.format.borehole.jsonio.pcbh_from_dict(value, *, validate=True, max_boreholes=10000, max_intervals=1000000, max_nesting=32)[source]

Build a PCBH document from a decoded JSON mapping.

Parameters:

  • value (mapping) – Decoded PCBH root object.

  • validate (bool, default True) – Run semantic validation before returning.

  • max_boreholes (int) – Positive resource limits applied before object construction.

  • max_intervals (int) – Positive resource limits applied before object construction.

  • max_nesting (int) – Positive resource limits applied before object construction.

Returns:

Parsed in-memory document.

Return type:

PCBHDocument

Raises:

  • ValueError – If structure, version, or resource limits are invalid.

  • PCBHValidationError – If semantic validation fails.

pycsamt.format.borehole.jsonio.read_pcbh(path, *, validate=True, max_bytes=16777216, max_boreholes=10000, max_intervals=1000000, max_nesting=32)[source]

Read a canonical PCBH JSON file.

Parameters:

  • path (path-like) – Input .pcbh.json file.

  • validate (bool, default True) – Run semantic validation before returning.

  • max_bytes (int) – Positive limits for untrusted input.

  • max_boreholes (int) – Positive limits for untrusted input.

  • max_intervals (int) – Positive limits for untrusted input.

  • max_nesting (int) – Positive limits for untrusted input.

Returns:

Parsed and optionally validated document.

Return type:

PCBHDocument

Raises:

  • OSError – If the file cannot be read.

  • UnicodeError – If the file is not UTF-8.

  • ValueError – If JSON, structure, version, or limits are invalid.

  • PCBHValidationError – If semantic validation fails.

pycsamt.format.borehole.jsonio.write_pcbh(document, path, *, validate=True, indent=2)[source]

Atomically write a canonical PCBH JSON file.

Parameters:

  • document (PCBHDocument) – Document to serialize.

  • path (path-like) – Destination path. Parent directories are created when needed.

  • validate (bool, default True) – Run semantic validation before writing.

  • indent (int, default 2) – Positive JSON indentation width.

Returns:

Destination path.

Return type:

pathlib.Path

Raises:

  • TypeError – If document is not a PCBH document.

  • ValueError – If validation, JSON values, or indent are invalid.

  • OSError – If the atomic write fails.

Notes

The temporary file is created beside the destination so os.replace() remains an atomic same-filesystem operation.