euromod_linking.session
=======================

.. py:module:: euromod_linking.session

.. autoapi-nested-parse::

   Shared, long-lived EUROMOD connector session.

   Owns the single process-wide euromod.Model object and the lock that serializes
   all connector access (reads and simulation runs). No business logic and no
   mutation helpers — the model is used read-only at runtime; the only simulation
   overrides go through System.run() kwargs, which do not mutate the model.



Attributes
----------

.. autoapisummary::

   euromod_linking.session.model_lock


Exceptions
----------

.. autoapisummary::

   euromod_linking.session.ModelLookupError


Functions
---------

.. autoapisummary::

   euromod_linking.session.adopt
   euromod_linking.session.get_country
   euromod_linking.session.get_model
   euromod_linking.session.get_system


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

.. py:exception:: ModelLookupError(message: str, available: list | None = None)



   Raised when a country/system is not found. ``.available`` lists the names
   that would have worked, so a caller can report them.


   .. py:attribute:: available
      :value: []



.. py:function:: adopt(system) -> bool

   Make the model behind `system` the one this process reads from.

   Callers hand `apply_scenario` a live System they built themselves; the read
   helpers underneath resolve the model from here. Adopting the caller's own
   model closes that gap, so nobody has to load the model twice or through a
   particular door for income-list expansion to work.

   Returns True when a model was adopted. Silent False when `system` is not a
   live connector object — the caller may have loaded a model already, and this
   is a convenience, not a precondition.


.. py:function:: get_country(country_code: str, model_path: str | None = None)

   Return the live Country object, or raise ModelLookupError(available=[...]).


.. py:function:: get_model(model_path: str | None = None)

   Return the cached euromod.Model, loading it once per process.

   Pass `model_path` to load (or switch to) a model; omit it to reuse the one
   already loaded, which is how callers deep in a call chain avoid threading
   the path through every function. Loading is expensive (.NET + the whole
   model graph), so a genuinely different path is the only thing that reloads.


.. py:function:: get_system(country_code: str, system_name: str, model_path: str | None = None)

   Return the live System object, or raise ModelLookupError(available=[...]).


.. py:data:: model_lock