Allow easier import of NUTS regions (#436)

* Allow easier import of NUTS regions

* Update docs

docs/user_guide/config.rst

@@ -126,12 +126,12 @@ By setting *definitions.region.nuts* (optional) in the configuration file:
       nuts:
         nuts-1: [ AT, BE, CZ ]
         nuts-2: [ AT ]
-        nuts-3: [ AT, BE ]
+        nuts-3: true
 
 the nomenclature package will add the selected NUTS regions to the *region* codelist.
 
-In the example above, the package will add all NUTS (1, 2, and 3) for Austria,
-NUTS 1 and 3 for Belgium, and NUTS 1 for Czechia.
+In the example above, the package will add: NUTS 1 regions for Austria, Belgium
+and Czechia, NUTS 2 regions for Austria, NUTS 3 regions for all EU countries.
 
 More details on the list of NUTS regions can be found here: :ref:`nuts`.
 

nomenclature/codelist.py

@@ -733,11 +733,16 @@ def from_directory(
         # adding nuts regions
         if config.definitions.region.nuts:
             for level, countries in config.definitions.region.nuts.items():
-                for nuts_region in nuts.get(
-                    level=int(level[-1]), country_code=countries
-                ):
+                if countries is True:
+                    region_list = nuts.get(level=int(level[-1]))
+                else:
+                    region_list = nuts.get(level=int(level[-1]), country_code=countries)
+                for r in region_list:
                     code_list.append(
-                        RegionCode(name=nuts_region.code, hierarchy="NUTS 2021-2024")
+                        RegionCode(
+                            name=r.code,
+                            hierarchy=f"NUTS {level[-1]} regions (2021-2024)",
+                        )
                     )
 
         # importing from an external repository

nomenclature/config.py

@@ -107,13 +107,13 @@ def repository_dimension_path(self) -> str:
 
 class RegionCodeListConfig(CodeListConfig):
     country: bool = False
-    nuts: dict[str, str | list[str]] | None = None
+    nuts: dict[str, str | list[str] | bool] | None = None
 
     @field_validator("nuts")
     @classmethod
     def check_nuts(
-        cls, v: dict[str, str | list[str]] | None
-    ) -> dict[str, str | list[str]] | None:
+        cls, v: dict[str, str | list[str] | bool] | None
+    ) -> dict[str, str | list[str] | bool] | None:
         if v and not all(k in ["nuts-1", "nuts-2", "nuts-3"] for k in v.keys()):
             raise ValueError(
                 "Invalid fields for `nuts` in configuration. "

tests/test_definition.py

@@ -70,7 +70,9 @@ def test_definition_general_config_nuts_only():
     obs = DataStructureDefinition(
         TEST_DATA_DIR / "config" / "general-config-only-nuts" / "definitions"
     )
+    # check country codes
     assert all(region[:2] in ("AT", "BE", "CZ") for region in obs.region)
+    # check region import
     assert len([region for region in obs.region if region.startswith("AT")]) == 4
     assert len([region for region in obs.region if region.startswith("BE")]) == 12
     assert len([region for region in obs.region if region.startswith("CZ")]) == 15