2.11.1.3. pycsamt.jones.cbase#

Classes

`JCBBase`([items, verbose])	Minimal stateful base for collections of J files.
`JCoreParser`(*[, recursive, strict, on_dup, ...])	Core scanner for J files that extracts light metadata.
`JParseMixin`()	Lightweight helpers for scanning Jones J-format text.

class pycsamt.jones.cbase.JParseMixin[source]

Bases: object

Lightweight helpers for scanning Jones J-format text.

The mixin implements tolerant, file-level utilities used by higher-level parsers and collections. It focuses on small, dependency-free pieces such as path coercion, candidate file discovery, banner and header probing, and quick content reads.

The mixin does not keep state. Methods are small and side-effect free so they can be reused by different classes (e.g., JCoreParser, JCBBase, JCollection).

Notes

Utilities are designed to be permissive. They handle odd encodings, mixed line endings, and common filename patterns. They also accept both pathlib.Path and strings.

The intent is to keep the heavy parsing in dedicated readers, while providing robust file discovery and quick checks here.

Examples

Discover candidate files in a folder:

>>> m = JParseMixin()
>>> root = "data/j"
>>> list(m._iter_j_files([root]))[:1]
[PosixPath('...kb0-s001.txt')]

Coerce user inputs to Path:

>>> p = m._as_path("data/j/kb0-s001.txt")
>>> p.exists()
True

See also

JCoreParser: Adds content probing (station, dtype, counts).
JCBBase: State-holding base for collections.
pycsamt.jones.validation.IsJ: File-level validator for J candidates.
pycsamt.jones.j.JFile: High-level reader that builds Z/Tipper/R blocks.

References

[JParseMixin-1]

1. Jones (1994). J-format v2.0. MTNet notes.

J_SUFFIXES = {'.dat', '.j', '.jones', '.txt'}

is_j_like(src, *, deep=True)[source]

Light heuristic to decide if src looks like a Jones file.

Parameters:

src (path-like) – File path.
deep (bool, default=True) – If False, only extension + existence is checked.

Returns:

True if the file looks like J-format.

Return type:

bool

is_j_file(src, *, deep=True)[source]

Spec-level check via IsJ. Returns True if the file satisfies the structural requirements; False otherwise. Never raises.

Parameters:

src (str | Path)
deep (bool)

Return type:

bool

is_j_candidate(src, *, deep=True)[source]

Alias of is_j_like(). Some call-sites prefer this name.

Parameters:

src (str | Path)
deep (bool)

Return type:

bool

class pycsamt.jones.cbase.JCoreParser(*, recursive=True, strict=False, on_dup='replace', verbose=0)[source]

Bases: JParseMixin

Core scanner for J files that extracts light metadata.

Extends JParseMixin with small, read-only probes that inspect the top header and first data head triple. This class can reveal the station code, presence of info keys, encountered data kinds, and the declared row count of the first block. It avoids loading the whole file.

The implementation aims to be fast and safe for directory crawls, where many files are filtered before full parse.

Variables:

encoding (str, default 'utf-8') – Encoding used when reading text. Implementations may choose a tolerant variant such as 'utf-8-sig' with errors='replace'.

Parameters:

recursive (bool)
strict (bool)
on_dup (str)
verbose (int)

_read_text(path): Return the file content as a single text string.

_scan_one(path): Return a small dict of hints (e.g., station, kinds, nrows) obtained without full parsing.

_looks_like_j(path): Heuristic check that a path is a J candidate.

_iter_info_keys(text): Yield info keys (>KEY=VALUE) from the header area.

Notes

The scanner is structural. It does not validate numeric content or cross-block consistency. It is designed to be called many times in batch workflows.

Examples

Quick peek of a single file:

>>> p = "data/j/kb0-s001.txt"
>>> core = JCoreParser()
>>> hints = core._scan_one(p)
>>> "station" in hints and "kinds" in hints
True

Filter a folder to J candidates:

>>> paths = list(core._iter_j_files(["data/j"]))
>>> all(core._looks_like_j(p) for p in paths)
True

See also

JParseMixin: Path and discovery helpers used by this scanner.
JCBBase: Collection base that can cache these hints.
pycsamt.jones.heads.Heads: Full header reader (Info + Head + Banner).
pycsamt.jones.blocks.JBlocks: Full data block reader.

References

[JCoreParser-1]

1. Jones (1994). J-format v2.0. MTNet notes.

results: list[_JParseResult]

parse(sources)[source]

Parameters:: sources (str | Path | Sequence[str | Path])
Return type:: list[JFile]

errors()[source]

Return type:: list[tuple[Path, BaseException]]

class pycsamt.jones.cbase.JCBBase(items=None, *, verbose=0)[source]

Bases: object

Minimal stateful base for collections of J files.

The class manages a list of parsed items (usually JFile), keeps light metadata for indexing and filtering, and offers a stable surface for higher-level collection types. It is intentionally small so projects can extend it without tight coupling.

Parameters:

verbose (int, default 0) – Verbosity for logs and warnings. Implementations are free to ignore it or to pass it to child readers.
items (Iterable[JFile] | None)

Variables:

items (list) – Stored per-file objects. The class does not enforce a specific type, but JFile is the natural choice.
n (int) – Number of stored items.
paths (list of Path) – Convenience view of the underlying file paths (when available on items).

add(obj)[source]

Append an item. Returns the item for chaining.

Parameters:: jf (JFile)
Return type:: None

parse(paths): Build and add items from paths. Uses the light probes from JCoreParser before full parse.

filter(**kws): Optional helper that returns a new instance filtered by station, component family, or other metadata.

__len__(), __iter__()[source]: Python container protocol for lists of items.

Notes

Subclasses are encouraged to keep the API stable while augmenting with domain-specific helpers, like saving index CSV files or computing per-site quality metrics.

The base class uses tolerant discovery, so it can be used on mixed folders where some files are not Jones J-format.

Examples

Build a collection from a folder:

>>> col = JCBBase(verbose=0)
>>> items = col.parse(["data/j"])
>>> len(items) == col.n
True

Iterate over sites and write quick summaries:

>>> for it in col:
...     print(getattr(it, "site", None))