pycsamt.jones.utils#

Lightweight parsing utilities for A.G. Jones J‑format files.

This module exposes small, focused helpers used by higher‑level components (e.g., j.py, components.py) to lex and parse J files. It does not assemble site objects; it only handles normalization, tokenization, and row conversion with robust error messages.

Functions

is_blank(s)

Return True if s is blank or whitespace only.

is_comment(s)

Return True if s is a comment line.

iter_info(lines)

Yield (key, value) pairs from information lines.

iter_lines(obj, *[, encoding, keepends])

Yield lines from a path, file‑like, or a sequence of strings.

iter_rows(kind, lines)

Yield ParsedRow objects for rows of kind.

parse_datatype_units(line, *[, lineno])

Parse a data‑type line like ZXY SI or RTE.

parse_info(line, *[, lineno])

Parse an information line >KEY = value.

parse_npoints(line, *[, lineno])

Parse the number of rows to follow.

parse_row(kind, line, *[, lineno])

Parse a single data row for kind.

parse_station(line, *[, lineno])

Parse a station line (alnum up to 6 chars).

strip_nondata(lines)

Yield only non‑comment lines (keep blanks for block logic).

Classes

DataType(kind, comp, units[, tensor_hint])

Decoded data‑type descriptor.

ParsedRow(period, freq, values, flags)

A normalized row from an R/S or TF block.
exception pycsamt.jones.utils.JParseError#

Bases: PycsamtError

Raised when a J‑file token cannot be parsed.

The message tries to include the line number and a short hint about the expected syntax to aid debugging.

class pycsamt.jones.utils.DataType(kind, comp, units, tensor_hint=None)[source]#

Bases: object

Decoded data‑type descriptor.

Variables:

  • kind (str) – One of R, S, Z, Q, C, T (upper‑case).

  • comp (str) – Two‑letter component code, e.g., XY or mode TE.

  • units (str | None) – Canonical units string ("ohms" or "mV/km/nT") or None if not specified.

  • tensor_hint (str | None) – For TE/TM, the canonical tensor entry (e.g., RXY), else None.

Parameters:

  • kind (str)

  • comp (str)

  • units (str | None)

  • tensor_hint (str | None)

kind: str#
comp: str#
units: str | None#
tensor_hint: str | None = None#
class pycsamt.jones.utils.ParsedRow(period, freq, values, flags)[source]#

Bases: object

A normalized row from an R/S or TF block.

Variables:

  • period (float) – Period in seconds (always positive).

  • freq (float) – Frequency in Hz (1/period). If input stored frequency, freq equals that value and period is inverted.

  • values (Mapping[str, float]) – Other numeric columns by name.

  • flags (Mapping[str, bool]) – Flags such as stored_as_freq or rejected.

Parameters:
period: float#
freq: float#
values: Mapping[str, float]#
flags: Mapping[str, bool]#
pycsamt.jones.utils.iter_lines(obj, *, encoding='utf-8', keepends=False)[source]#

Yield lines from a path, file‑like, or a sequence of strings.

Parameters:

  • obj (file‑like | str | Path | sequence of str) – Source to read from. Paths are opened in text mode.

  • encoding (str, default="utf-8") – Text encoding used for paths.

  • keepends (bool, default=False) – Whether to keep line endings in yielded strings.

Yields:

str – One line at a time.

Return type:

Iterator[str]

pycsamt.jones.utils.is_comment(s)[source]#

Return True if s is a comment line.

Parameters:

s (str)

Return type:

bool

pycsamt.jones.utils.is_blank(s)[source]#

Return True if s is blank or whitespace only.

Parameters:

s (str)

Return type:

bool

pycsamt.jones.utils.parse_info(line, *, lineno=None)[source]#

Parse an information line >KEY = value.

Returns the canonical attribute name and the raw value string.

Parameters:

  • line (str)

  • lineno (int | None)

Return type:

tuple[str, str]

pycsamt.jones.utils.parse_station(line, *, lineno=None)[source]#

Parse a station line (alnum up to 6 chars).

Parameters:

  • line (str)

  • lineno (int | None)

Return type:

str

pycsamt.jones.utils.parse_datatype_units(line, *, lineno=None)[source]#

Parse a data‑type line like ZXY SI or RTE.

The result contains the kind, component, optional units, and a tensor_hint for TE/TM modes.

Parameters:

  • line (str)

  • lineno (int | None)

Return type:

DataType

pycsamt.jones.utils.parse_npoints(line, *, lineno=None)[source]#

Parse the number of rows to follow.

Parameters:

  • line (str)

  • lineno (int | None)

Return type:

int

pycsamt.jones.utils.parse_row(kind, line, *, lineno=None)[source]#

Parse a single data row for kind.

Handles R/S (rho‑phi) and complex TF kinds (Z/Q/C/T). Returns a ParsedRow with period/frequency normalized and rejection flags applied according to the spec.

Parameters:
Return type:

ParsedRow

pycsamt.jones.utils.strip_nondata(lines)[source]#

Yield only non‑comment lines (keep blanks for block logic).

This keeps structure intact while removing comment noise.

Parameters:

lines (Iterable[str])

Return type:

Iterator[str]

pycsamt.jones.utils.iter_info(lines)[source]#

Yield (key, value) pairs from information lines.

Stops when the first non‑info, non‑comment, non‑blank line is encountered. Suitable for reading the header block.

Parameters:

lines (Iterable[str])

Return type:

Iterator[tuple[str, str]]

pycsamt.jones.utils.iter_rows(kind, lines)[source]#

Yield ParsedRow objects for rows of kind.

Parameters:

  • kind (str) – One of R, S, Z, Q, C, T.

  • lines (iterable of str) – The raw lines containing only the row body.

Return type:

Iterator[ParsedRow]