aeat.domain.manuals._fetch module

Raw manual-part downloader and manifest writer.

The fetcher speaks httpx directly: the PartSpec table below hard-codes the verified canonical AEAT URLs for every (manual_id, year, part) triple the subpackage supports. The fetch CLI looks up a triple in the table, streams the PDF to disk, computes its sha256 on the fly, and writes a FetchedManualPart manifest next to the raw binary.

class PartSpec(**data)[source]

Bases: BaseModel

Canonical source URL for a (manual_id, year, part) triple.

Strict and frozen so the public surface stays on pydantic v2 per the project mandate; held as a static tuple in PART_SPECS and never constructed from untrusted input.

Variables:

  • manual_id – Handbook identifier.

  • year – Tax year.

  • part – Volume split within the year.

  • source_pdf_url – Canonical AEAT URL the PDF is fetched from.

Parameters:
manual_id: ManualId
year: int
part: ManualPart
source_pdf_url: str
class FetchResult(**data)[source]

Bases: BaseModel

Thin wrapper returned by fetch_manual_part() to the CLI.

Variables:

  • manifest – The FetchedManualPart record written next to the raw PDF.

  • part_root – Resolved directory root for the manual part.

  • pdf_path – Absolute path to the freshly downloaded PDF.

  • manifest_path – Absolute path to the JSON manifest on disk.

Parameters:
manifest: FetchedManualPart
part_root: Path
pdf_path: Path
manifest_path: Path
lookup_spec(manual_id, year, part)[source]

Look up a canonical source URL for a (manual_id, year, part) triple.

Parameters:

  • manual_id (ManualId) – Handbook identifier.

  • year (int) – Tax year.

  • part (ManualPart) – Volume split within the year.

Return type:

PartSpec

Returns:

The matching PartSpec.

Raises:

ManifestError – If no entry exists in PART_SPECS.

write_manifest(manifest_path, manifest)[source]

Serialise a FetchedManualPart as indented JSON on disk.

Parameters:

  • manifest_path (Path) – Destination path for the JSON manifest.

  • manifest (FetchedManualPart) – Manifest record to serialise.

Raises:

ManifestError – If the file cannot be written due to an OS error.

Return type:

None

load_manifest(manifest_path)[source]

Load and validate a manifest from disk.

Parameters:

manifest_path (Path) – Path to a manifest.json file.

Return type:

FetchedManualPart

Returns:

The parsed FetchedManualPart record.

Raises:

ManifestError – If the file is missing, malformed, or fails schema validation.

fetch_manual_part(*, manual_id, year, part, settings=None)[source]

Download a manual part and write its sha256-verified manifest.

Parameters:

  • manual_id (ManualId) – Handbook identifier.

  • year (int) – Tax year.

  • part (ManualPart) – Volume split within the year.

  • settings (Settings | None) – Optional settings instance; loaded on demand otherwise.

Return type:

FetchResult

Returns:

A FetchResult containing the manifest and the resolved paths for the raw PDF and the manifest JSON.

Raises:

ManifestError – If the canonical URL is unknown or the download fails.

verify_fetched_pdf(manifest, part_root)[source]

Re-hash the on-disk PDF and compare against the manifest sha256.

Parameters:

  • manifest (FetchedManualPart) – The manifest record to verify against.

  • part_root (Path) – Directory containing the raw PDF.

Raises:

ManifestError – If the PDF is missing or its sha256 diverges.

Return type:

None