euromod_linking.ingest
======================

.. py:module:: euromod_linking.ingest

.. autoapi-nested-parse::

   Universal shock ingest: (external model output file, mapping spec) ->
   canonical shock-table records.

   Mapping specs are declarative, repo-versioned YAML files in
   ``euromod_linking/mappings/``, validated against ``mapping.v1.schema.json``.
   Anything a spec cannot express becomes a new *named transform* here — mappings
   stay data, code stays reviewed.



Exceptions
----------

.. autoapisummary::

   euromod_linking.ingest.IngestError


Functions
---------

.. autoapisummary::

   euromod_linking.ingest.ingest
   euromod_linking.ingest.list_mappings
   euromod_linking.ingest.load_mapping


Module Contents
---------------

.. py:exception:: IngestError



   Inappropriate argument value (of correct type).


.. py:function:: ingest(file_path: str, mapping, country: str | None = None) -> tuple[list[dict], list[str]]

   Read an external model output file through a mapping spec.

   Returns (records, warnings). ``country`` filters rows to one country when a
   group derivation uses the nuts_code transform, for files covering several.
   Raises IngestError on structural problems.


.. py:function:: list_mappings() -> list[dict]

   Available mapping specs: [{name, description, file}].


.. py:function:: load_mapping(name_or_spec) -> dict

   Load + schema-validate a mapping spec by name (mappings/{name}.yaml)
   or as an already-parsed dict.