get method and typing (#16)

Category: feature
JIRA issue: https://jira.ihme.washington.edu/browse/MIC-5215

Changes and notes
Add get method and update typing.

Testing
Wrote new tests. All tests pass.

Author: hussain-jafari

CHANGELOG.rst

@@ -1,3 +1,7 @@
+**2.1.0 - 10/31/2024**
+
+ - Add getter methods
+
 **2.0.2 - 08/01/2024**
 
  - Create explicit iterator for LayeredConfigTree

docs/nitpick-exceptions

@@ -1,6 +1,4 @@
-from typing import Optional
-
-from layered_config_tree.types import NestedDictValue
+from typing import Any, Optional
 
 
 class ConfigurationError(Exception):
@@ -37,7 +35,7 @@ def __init__(
         name: str,
         layer: Optional[str],
         source: Optional[str],
-        value: NestedDictValue,
+        value: Any,
     ):
         self.layer = layer
         self.source = source

src/layered_config_tree/exceptions.py

@@ -40,7 +40,7 @@
     ConfigurationKeyError,
     DuplicatedConfigurationError,
 )
-from layered_config_tree.types import InputData, NestedDict, NestedDictValue, NodeValue
+from layered_config_tree.types import InputData
 
 
 class ConfigNode:
@@ -74,7 +74,7 @@ class ConfigNode:
     def __init__(self, layers: list[str], name: str):
         self._name = name
         self._layers = layers
-        self._values: dict[str, tuple[Optional[str], NodeValue]] = {}
+        self._values: dict[str, tuple[Optional[str], Any]] = {}
         self._frozen = False
         self._accessed = False
 
@@ -89,7 +89,7 @@ def accessed(self) -> bool:
         return self._accessed
 
     @property
-    def metadata(self) -> list[dict[str, Union[Optional[str], NodeValue]]]:
+    def metadata(self) -> list[dict[str, Union[Optional[str], Any]]]:
         """Returns all values and associated metadata for this node."""
         result = []
         for layer in self._layers:
@@ -112,7 +112,7 @@ def freeze(self) -> None:
         """
         self._frozen = True
 
-    def get_value(self, layer: Optional[str] = None) -> NodeValue:
+    def get_value(self, layer: Optional[str] = None) -> Any:
         """Returns the value at the specified layer.
 
         If no layer is specified, the outermost (highest priority) layer
@@ -133,7 +133,7 @@ def get_value(self, layer: Optional[str] = None) -> NodeValue:
         self._accessed = True
         return value
 
-    def update(self, value: NodeValue, layer: Optional[str], source: Optional[str]) -> None:
+    def update(self, value: Any, layer: Optional[str], source: Optional[str]) -> None:
         """Set a value for a layer with optional metadata about source.
 
         Parameters
@@ -180,7 +180,7 @@ def update(self, value: NodeValue, layer: Optional[str], source: Optional[str])
         else:
             self._values[layer] = (source, value)
 
-    def _get_value_with_source(self, layer: Optional[str]) -> tuple[Optional[str], NodeValue]:
+    def _get_value_with_source(self, layer: Optional[str]) -> tuple[Optional[str], Any]:
         """Returns a (source, value) tuple at the specified layer.
 
         If no layer is specified, the outermost (highest priority) layer
@@ -232,10 +232,10 @@ class ConfigIterator:
     This iterator is used to iterate over the keys of a LayeredConfigTree object.
     """
 
-    def __init__(self, config_tree: "LayeredConfigTree"):
+    def __init__(self, config_tree: LayeredConfigTree):
         self._iterator = iter(config_tree._children)
 
-    def __iter__(self) -> "ConfigIterator":
+    def __iter__(self) -> ConfigIterator:
         return self
 
     def __next__(self) -> str:
@@ -252,7 +252,7 @@ class LayeredConfigTree:
 
     # Define type annotations here since they're indirectly defined below
     _layers: list[str]
-    _children: dict[str, Union["LayeredConfigTree", "ConfigNode"]]
+    _children: dict[str, Union[LayeredConfigTree, ConfigNode]]
     _frozen: bool
     _name: str
 
@@ -308,7 +308,7 @@ def freeze(self) -> None:
         for child in self.values():
             child.freeze()
 
-    def items(self) -> Iterable[tuple[str, Union["LayeredConfigTree", ConfigNode]]]:
+    def items(self) -> Iterable[tuple[str, Union[LayeredConfigTree, ConfigNode]]]:
         """Return an iterable of all (child_name, child) pairs."""
         return self._children.items()
 
@@ -332,7 +332,7 @@ def unused_keys(self) -> list[str]:
                     unused.append(f"{name}.{grandchild_name}")
         return unused
 
-    def to_dict(self) -> NestedDict:
+    def to_dict(self) -> dict[str, Any]:
         """Converts the LayeredConfigTree into a nested dictionary.
 
         All metadata is lost in this conversion.
@@ -343,12 +343,38 @@ def to_dict(self) -> NestedDict:
             if isinstance(child, ConfigNode):
                 result[name] = child.get_value(layer=None)
             else:
-                result[name] = child.to_dict()  # type: ignore[assignment]
+                result[name] = child.to_dict()
         return result
 
-    def get_from_layer(
-        self, name: str, layer: Optional[str] = None
-    ) -> Union[NodeValue, "LayeredConfigTree"]:
+    def get(self, key: str, default_value: Any = None) -> Any:
+        """Return the LayeredConfigTree or value at the key in the outermost layer of the config tree.
+
+        Parameters
+        ----------
+        key
+            The string to look for in the outermost layer of the config tree.
+        default_value
+            The value to return if key is not found
+        """
+        return self[key] if key in self._children else default_value
+
+    def get_tree(self, key: str) -> LayeredConfigTree:
+        """Return the LayeredConfigTree at the key in the outermost layer of the config tree.
+
+        Parameters
+        ----------
+        key
+            The str we look up in the outermost layer of the config tree.
+        """
+        data = self[key]
+        if isinstance(data, LayeredConfigTree):
+            return data
+        else:
+            raise ConfigurationError(
+                f"The data you accessed using {key} with get_tree was of type {type(data)}, but get_tree must return a LayeredConfigTree."
+            )
+
+    def get_from_layer(self, name: str, layer: Optional[str] = None) -> Any:
         """Get a configuration value from the provided layer.
 
         If no layer is specified, the outermost (highest priority) layer
@@ -420,7 +446,7 @@ def update(
             for k, v in data.items():
                 self._set_with_metadata(k, v, layer, source)
 
-    def metadata(self, name: str) -> list[NestedDict]:
+    def metadata(self, name: str) -> list[dict[str, Any]]:
         if name in self:
             return self._children[name].metadata  # type: ignore[return-value]
         name = f"{self._name}.{name}" if self._name else name
@@ -430,7 +456,7 @@ def metadata(self, name: str) -> list[NestedDict]:
     def _coerce(
         data: InputData,
         source: Optional[str],
-    ) -> tuple[NestedDict, Optional[str]]:
+    ) -> tuple[dict[str, Any], Optional[str]]:
         """Coerces data into dictionary format."""
         if isinstance(data, dict):
             return data, source
@@ -465,7 +491,7 @@ def _coerce(
     def _set_with_metadata(
         self,
         name: str,
-        value: Union[NestedDictValue, str, Path, "LayeredConfigTree"],
+        value: Any,
         layer: Optional[str],
         source: Optional[str],
     ) -> None:
@@ -519,9 +545,9 @@ def _set_with_metadata(
                     f"Can't assign a value to a LayeredConfigTree.", name
                 )
 
-        self._children[name].update(value, layer, source)  # type: ignore[arg-type]
+        self._children[name].update(value, layer, source)
 
-    def __setattr__(self, name: str, value: NestedDictValue) -> None:
+    def __setattr__(self, name: str, value: Any) -> None:
         """Set a value on the outermost layer."""
         if name not in self:
             raise ConfigurationKeyError(
@@ -530,7 +556,7 @@ def __setattr__(self, name: str, value: NestedDictValue) -> None:
             )
         self._set_with_metadata(name, value, layer=None, source=None)
 
-    def __setitem__(self, name: str, value: NestedDictValue) -> None:
+    def __setitem__(self, name: str, value: Any) -> None:
         """Set a value on the outermost layer."""
         if name not in self:
             raise ConfigurationKeyError(
@@ -554,14 +580,14 @@ def __getattr__(self, name: str) -> Any:
     # * Calling __getattr__ before we have set up the state doesn't work,
     #   because it leads to an infinite loop looking for the module's
     #   actual attributes (not config keys)
-    def __getstate__(self) -> NestedDict:
+    def __getstate__(self) -> dict[str, Any]:
         return self.__dict__
 
-    def __setstate__(self, state: NestedDict) -> None:
+    def __setstate__(self, state: dict[str, Any]) -> None:
         for k, v in state.items():
             self.__dict__[k] = v
 
-    def __getitem__(self, name: str) -> Union[NodeValue, "LayeredConfigTree"]:
+    def __getitem__(self, name: str) -> Any:
         """Get a value from the outermost layer in which it appears."""
         return self.get_from_layer(name)
 

src/layered_config_tree/main.py

@@ -1,21 +1,10 @@
+from __future__ import annotations
+
 from pathlib import Path
-from typing import TYPE_CHECKING, Mapping, Union
+from typing import TYPE_CHECKING, Any, Union
 
 if TYPE_CHECKING:
     from layered_config_tree import LayeredConfigTree
 
-
-# NOTE: py 3.9 does not support typing.TypeAlias
-
-# Define a nested dictionary of unknown depth for type hinting
-NestedDict = Mapping[str, "NestedDictValue"]
-# Define the leaf (ConfigNode) values (which cannot be another dictionary)
-NodeValue = Union[str, int, float, list[Union[str, int, float]]]
-# Define a NestedDictionary value which can be either a ConfigNodeValue or another NestedDict
-# NOTE: Due to the forward reference to NestedDictValue above, static type checkers
-#   (e.g. mypy) may not be able to determine the correct type of NestedDictValue;
-#   use # type: ignore as required
-NestedDictValue = Union[NodeValue, NestedDict]
-
 # Data input types
-InputData = Union[NestedDict, str, Path, "LayeredConfigTree"]
+InputData = Union[dict[str, Any], str, Path, "LayeredConfigTree"]

src/layered_config_tree/types.py

@@ -1,6 +1,7 @@
 import pickle
 import textwrap
 from pathlib import Path
+from typing import Any
 
 import pytest
 import yaml
@@ -12,7 +13,6 @@
     DuplicatedConfigurationError,
     LayeredConfigTree,
 )
-from layered_config_tree.types import NestedDict
 
 
 @pytest.fixture(params=list(range(1, 5)))
@@ -43,6 +43,14 @@ def empty_tree(layers: list[str]) -> LayeredConfigTree:
     return LayeredConfigTree(layers=layers)
 
 
+@pytest.fixture
+def getter_dict() -> dict[str, Any]:
+    return {
+        "outer_layer_1": "test_value",
+        "outer_layer_2": {"inner_layer": "test_value2"},
+    }
+
+
 def test_node_creation(empty_node: ConfigNode) -> None:
     assert not empty_node
     assert not empty_node.accessed
@@ -243,7 +251,7 @@ def test_tree_creation(empty_tree: LayeredConfigTree) -> None:
 
 
 def test_tree_coerce_dict() -> None:
-    data: NestedDict
+    data: dict[str, Any]
     data = {}
     src = "test"
     assert LayeredConfigTree._coerce(data, src) == (data, src)
@@ -458,6 +466,56 @@ def test_to_dict_yaml(test_spec: Path) -> None:
     assert yaml_config == lct.to_dict()
 
 
+@pytest.mark.parametrize(
+    "key, default_value, expected_value",
+    [
+        ("outer_layer_1", None, "test_value"),
+        ("outer_layer_1", "some_default", "test_value"),
+        ("fake_key", 0, 0),
+        ("fake_key", "some_default", "some_default"),
+    ],
+)
+def test_getter_single_values(
+    key: str, default_value: str, expected_value: str, getter_dict: dict[str, Any]
+) -> None:
+    lct = LayeredConfigTree(getter_dict)
+
+    if default_value is None:
+        assert lct.get(key) == expected_value
+    else:
+        assert lct.get(key, default_value) == expected_value
+
+
+def test_getter_chained(getter_dict: dict[str, Any]) -> None:
+    lct = LayeredConfigTree(getter_dict)
+
+    outer_layer_2 = lct.get("outer_layer_2")
+    assert isinstance(outer_layer_2, LayeredConfigTree)
+    assert outer_layer_2.to_dict() == getter_dict["outer_layer_2"]
+    assert outer_layer_2.get("inner_layer") == "test_value2"
+
+
+def test_getter_default_values(getter_dict: dict[str, Any]) -> None:
+    lct = LayeredConfigTree(getter_dict)
+
+    assert lct.get("fake_key") is None
+
+    default_value = lct.get("fake_key", {})
+    # checking default_value equals {} is not enough for mypy to know it's a dict
+    assert default_value == {} and isinstance(default_value, dict)
+    assert default_value.get("another_fake_key") is None
+
+
+def test_tree_getter(getter_dict: dict[str, Any]) -> None:
+    lct = LayeredConfigTree(getter_dict)
+
+    assert lct.get_tree("outer_layer_2").to_dict() == getter_dict["outer_layer_2"]
+    with pytest.raises(ConfigurationError, match="must return a LayeredConfigTree"):
+        lct.get_tree("outer_layer_1")
+    with pytest.raises(ConfigurationError, match="No value at name"):
+        lct.get_tree("fake_key")
+
+
 def test_equals() -> None:
     # TODO: Assert should succeed, instead of raising, once equality is
     # implemented for LayeredConfigTrees