aeat.core.resources._boundary module

Single boundary for reading bundled corpus and registry data.

Bundled trees live at aeat/_data/corpus/... and aeat/_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 PROJECT_ROOT walk. Use bundled_path() when a process-lifetime Path is required, and as_path() for a scoped materialised path. The PROJECT_ROOT walk is reserved for var/ operator outputs in aeat.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 slim aeat runtime wheel and shipped in an optional aeat_data companion distribution whose layout mirrors aeat/_data. resolve_corpus_binary() is the single importlib.resources seam that resolves such a binary from the aeat tree first and then the companion, so a full checkout and a split install read a corpus binary uniformly; resolve_companion_binary() resolves the companion side alone. A missing companion is a not-present signal (None), never an exception leak.

packaged_data(*parts)

Return a Traversable rooted at aeat/_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("aeat") 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:

Iterator[Path]

resolve_companion_binary(*parts)

Resolve a corpus binary from the optional aeat_data companion alone.

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 companion is installed and carries the binary, else None. The companion mirrors aeat/_data, so the segments are identical to the ones packaged_data() takes.

resolve_corpus_binary(*parts)

Resolve a bundled corpus binary, the aeat tree first then the aeat_data companion.

parts are the segments under _data (e.g. "corpus", "aeat_official", "disenos_registro", "modelo_100", "files", "dr.xlsx"). The slim aeat wheel excludes _data/corpus/**/*.{pdf,xls,xlsx}; the optional aeat_data companion carries exactly those binaries under mirrored paths. This is the single importlib.resources seam that unifies the full-checkout read (binary in the aeat tree) and the split-install read (binary in the companion).

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)