cadrumo.core.resources.bundled_data module

Single boundary for reading bundled corpus and registry data.

Bundled trees live at cadrumo/_data/corpus/... and cadrumo/_data/registry/... inside the installed wheel via the hatchling force-include configuration in pyproject.toml. The same prefix resolves to the in-tree top-level corpus/ and registry/ directories under an editable install because hatchling honours the force-include mapping for both targets.

Callers MUST go through packaged_data() rather than computing the location from __file__ or a repo-root walk. Use bundled_path() when a process-lifetime Path is required, and as_path() for a scoped materialised path. The data-root anchor is reserved for var/ operator outputs in cadrumo.core.config and is not a valid resolution path for read-only bundled data.

The corpus source binaries (_data/corpus/**/*.{pdf,xls,xlsx}) are excluded from the command-bearing cadrumo wheel and shipped in two mandatory cadrumo_data companion distributions whose joined layout mirrors cadrumo/_data. resolve_corpus_binary() is the single importlib.resources seam that resolves such a binary from the cadrumo tree first and then the companion namespace, so a full checkout and an installed three-wheel cohort read a corpus binary uniformly. A missing companion remains a not-present signal (None) at this low-level resource boundary; the catalogue integrity boundary turns that signal into a hard failure.

Because the split is by file SUFFIX rather than by directory, a corpus directory is a single logical tree whose members can materialise under different installed roots: a design workbook resolves under cadrumo_data while the hand-authored declarations that annotate it stay under cadrumo. A reader that reaches a neighbouring file with pathlib.Path.with_name() therefore sees only the root its starting file happened to come from. bundled_data_roots() and resolve_data_root_copies() are the seam that spans them, so a neighbour is located by its position in the logical tree rather than by which distribution happens to carry the file next to it.

packaged_data(*parts)

Return a Traversable rooted at cadrumo/_data/<parts...>.

Parameters:

*parts (str) – One or more path segments joined under the bundled data root. Empty call returns the bundled root itself.

Return type:

Traversable

Returns:

A importlib.resources.abc.Traversable that callers may read via read_text / read_bytes / open or iterate via iterdir. Use as_path() when a real on-disk pathlib.Path is required.

bundled_path(*parts)

Return a process-lifetime pathlib.Path for a bundled subtree.

Suitable for module-level Settings field defaults that need a real on-disk path at import time. The underlying as_file context is entered into a module-level contextlib.ExitStack that is closed at interpreter exit. Under the supported install modes (editable hatchling, built wheel) the materialisation is a no-op: importlib.resources.files("cadrumo") resolves to a real on-disk directory and as_file returns the path unchanged.

Parameters:

*parts (str) – Path segments joined under the bundled data root.

Return type:

Path

Returns:

A pathlib.Path whose lifetime spans the running process. Callers MUST treat the path as read-only.

as_path(node)

Materialise node as a real on-disk path for the lifetime of the context.

importlib.resources.as_file extracts the resource to a temporary location when the underlying loader does not already expose a filesystem path. Under an editable install (hatchling force-include against the source tree) the materialised path is the in-tree location with no copy.

Parameters:

node (Traversable) – A Traversable returned by packaged_data() (or a descendant obtained via joinpath).

Yields:

A pathlib.Path that is valid only inside the with block. Callers MUST NOT retain the path beyond the context manager’s exit.

Return type:

Generator[Path]

resolve_companion_binary(*parts)

Resolve a corpus binary from the mandatory cadrumo_data namespace.

Parameters:

*parts (str) – Segments under the companion’s mirrored _data root (e.g. "corpus", "manuals", "renta", "2024", "source.pdf").

Return type:

Path | None

Returns:

A read-only pathlib.Path valid for the process lifetime when the joined companion namespace carries the binary, else None. The namespace mirrors cadrumo/_data, so the segments are identical to the ones packaged_data() takes.

resolve_corpus_binary(*parts)

Resolve a bundled corpus binary, the cadrumo tree first then the cadrumo_data companion.

parts are the segments under _data (e.g. "corpus", "aeat_official", "disenos_registro", "modelo_100", "files", "dr.xlsx"). The command-bearing Cadrumo wheel excludes _data/corpus/**/*.{pdf,xls,xlsx}; the mandatory cadrumo_data namespace carries exactly those binaries under mirrored paths. This is the single importlib.resources seam that unifies the full-checkout read (binary in the cadrumo tree) and the installed-cohort read (binary in a companion distribution).

Return type:

Path | None

Returns:

A read-only pathlib.Path valid for the process lifetime when the binary is present under either root, else None when it resolves under neither.

Parameters:

parts (str)

bundled_data_roots()

Return every installed root the bundled _data tree materialises under.

The cadrumo tree comes first and is always present; each installed cadrumo_data portion follows. Together they are the roots a single logical _data-relative path may resolve under, which is what makes the suffix-partitioned corpus one tree rather than three.

Return type:

tuple[Path, ...]

Returns:

The ordered roots, cadrumo first.

resolve_data_root_copies(path)

Return every existing copy of path across the bundled _data roots.

path is an ordinary filesystem path a caller computed by navigating from some other bundled file – a sibling annotation, a per-directory declaration. Whichever root path currently sits under, the same _data-relative position is checked under every other root, so a file and its neighbour are found together even when the distribution split placed them apart.

A path under no bundled root is left alone and answered from the filesystem: a temporary fixture or an operator-supplied file has no position in the logical tree, and inventing one for it would be a claim this seam cannot support.

Parameters:

path (Path) – The location to resolve, expressed in any one root’s coordinates.

Return type:

tuple[Path, ...]

Returns:

Every existing copy, in bundled_data_roots() order, so the first entry is the cadrumo tree’s copy whenever it has one. Empty when the file exists under no root. More than one entry means the same logical file is published by more than one distribution, which callers that cannot tolerate a silent winner must adjudicate.