Hierarchy Filter (first pull request)

doc/source/api.rst

@@ -1,15 +1,15 @@
-.. _api:
-
-.. currentmodule:: nomenclature
-
-API documentation
-=================
-
-.. toctree::
-   :maxdepth: 2
-
-   api/nomenclature
-   api/datastructuredefinition
-   api/codelist
-   api/regionprocessor
-   api/testing
+.. _api:
+
+.. currentmodule:: nomenclature
+
+API documentation
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   api/nomenclature
+   api/datastructuredefinition
+   api/codelist
+   api/regionprocessor
+   api/testing

doc/source/api/codelist.rst

@@ -1,7 +1,15 @@
-.. currentmodule:: nomenclature.codelist
-
-**CodeList**
-============
-
-.. autoclass:: CodeList
-   :members:
+.. currentmodule:: nomenclature.codelist
+
+**CodeList**
+============
+
+.. autoclass:: CodeList
+   :members:
+
+
+.. autoclass:: VariableCodeList
+   :members:
+
+
+.. autoclass:: RegionCodeList
+   :members:

nomenclature/codelist.py

@@ -111,7 +111,6 @@ def validate_items(self, items: List[str]) -> List[str]:
     def replace_tags(
         cls, code_list: List[Code], tag_name: str, tags: List[Code]
     ) -> List[Code]:
-
         _code_list: List[Code] = []
 
         for code in code_list:
@@ -524,7 +523,7 @@ def from_directory(cls, name: str, path: Path, file_glob_pattern: str = "**/*"):
             with open(yaml_file, "r", encoding="utf-8") as stream:
                 _code_list = yaml.safe_load(stream)
 
-            # a "region" codelist assumes a top-level key to be used as attribute
+            # a "region" codelist assumes a top-level category to be used as attribute
             for top_level_cat in _code_list:
                 for top_key, _codes in top_level_cat.items():
                     for item in _codes:
@@ -542,3 +541,47 @@ def from_directory(cls, name: str, path: Path, file_glob_pattern: str = "**/*"):
             mapping[code.name] = code
 
         return cls(name=name, mapping=mapping)
+
+    def filter(self, hierarchy: str) -> "RegionCodeList":
+        """A filter that returns the components within a provided hierarchy.
+
+        Parameters
+        ----------
+        hierarchy : str
+            The name of the hierarchy whose components you are looking for.
+        Raises
+        ------
+        ValueError
+            If User inputs a typo or a hierarchy not compatible with the given model.
+        Returns
+        -------
+        RegionCodeList
+            Returns a list of the component regions of the inputted hierarchy.
+        """
+
+        mapping = {k: v for k, v in self.mapping.items() if v.hierarchy == hierarchy}
+        if mapping:
+            return RegionCodeList(name=self.name, mapping=mapping)
+        else:
+            # creating list of possible hierarchies user can enter
+            avail_ops = []
+            for v in self.mapping.values():
+                # making sure there are no duplicates in avail_ops
+                if v.hierarchy not in avail_ops:
+                    avail_ops.append(v.hierarchy)
+            # creating the error message that will be displayed
+            n = len(avail_ops)
+            msg_1: str = f"No hierarchy found for {hierarchy}. Options available: "
+            if n - 1 >= 2:
+                # when there are three or more options
+                msg_3: str = (
+                    f"{'{} and {}'.format(', '.join(avail_ops[:-1]), avail_ops[-1])}"
+                )
+                raise ValueError(msg_1 + msg_3)
+            elif n - 1 == 1:
+                # when there are only two options
+                msg_2: str = f"{'{} and {}'.format(avail_ops[0], avail_ops[1])}"
+                raise ValueError(msg_1 + msg_2)
+            else:
+                # when there is only one option
+                raise ValueError(msg_1 + f"{avail_ops[0]}")

tests/data/region_codelist_four/four_region_hierarchies.yaml

@@ -0,0 +1,22 @@
+- First Region:
+  - World:
+      description: The entire world
+- Second Region:
+  - Some Country:
+      iso2: XY
+      iso3: XYZ
+- Third Region:
+  - ComponentA:
+      part1: windy
+      part2: rainy
+  - ComponentB:
+      part1: peatbogs
+      part2: forest
+- Fourth Region:
+  - North America:
+      country1: Canada
+      country2: USA
+      country3: Mexico
+  - South America:
+      country1: Brazil
+      country2: Argentina

tests/data/region_codelist_one/one_region_hierarchy.yaml

@@ -0,0 +1,3 @@
+- common:
+  - World:
+      definition: The entire world