Create dynamic country/NUTS region mapping via Eurostat with robust fallback

[Copilot]

This change removes hard-coded country/NUTS mappings and builds REGION_MAPPING dynamically from Eurostat data (countries + EU-wide NUTS2/NUTS3), while preserving current consumer behavior. It also adds deterministic fallback behavior so mapping remains stable when Eurostat data is unavailable or incomplete.

• Dynamic mapping pipeline in utils.py

  • Added pure loaders:
    • get_country_mapping()
    • get_nuts_mapping(level, country_prefix=None)
    • create_region_mapping()
  • Added regex-based filtering for valid code shapes:
    • countries: ^[A-Z]{2}$
    • NUTS2: ^[A-Z]{2}[A-Z0-9]{2}$
    • NUTS3: ^[A-Z]{2}[A-Z0-9]{3}$
  • Composed final mapping in deterministic precedence order:
    • countries -> NUTS2 -> NUTS3 -> COUNTRIES_SPECIAL_CASES

• Compatibility and resilience

  • Kept REGION_MAPPING as a plain dict[str, str] (no downstream interface changes).
  • Preserved pass-through behavior for unknown codes (REGION_MAPPING.get(code, code) remains valid).
  • Added graceful fallback to local static mappings for Eurostat import/network/data-shape failures.
  • Added explicit fallback warning to make source mode observable at runtime.

• Dependency updates

  • Added eurostat to project dependencies in:
    • pixi.toml
    • pyproject.toml

• Test suite updates (mapping-focused)

  • Reworked tests/test_utils.py to cover:
    • structure/type guarantees
    • required country coverage
    • NUTS2/NUTS3 presence
    • mocked Eurostat success path
    • mocked failure fallback path
    • partial-data fallback path
    • merge precedence (special cases override)
  • Extended integration assertions in:
    • tests/test_network_processor.py
    • tests/test_aggregation.py
  • Added mapping-flow checks for map_country_codes_to_names=True vs disabled pass-through.

def create_region_mapping() -> dict[str, str]:
    return (
        get_country_mapping()
        | get_nuts_mapping(level=2)
        | get_nuts_mapping(level=3)
        | COUNTRIES_SPECIAL_CASES
    )

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• ec.europa.eu
  • Triggering command: /home/REDACTED/.local/bin/pytest pytest tests/test_utils.py tests/test_network_processor.py tests/test_aggregation.py -v (dns block)
  • Triggering command: /home/REDACTED/.local/bin/pytest pytest tests/ -v (dns block)
  • Triggering command: /usr/bin/python python - (dns block)
• webgate.ec.europa.eu
  • Triggering command: /home/REDACTED/.local/bin/pytest pytest tests/test_utils.py tests/test_network_processor.py tests/test_aggregation.py -v (dns block)
  • Triggering command: /home/REDACTED/.local/bin/pytest pytest tests/ -v (dns block)
  • Triggering command: /usr/bin/python python - (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)