feat: ✨ add get_nested_attr() (#1039)

## Description

This PR adds a utility function for making it easier to access nested
properties on objects.
Our Properties class structure has lots of nesting and all attributes
default to None, so when I want to access a nested attribute (e.g.
`resource_properties.dialect.header`) I always have to make sure it
doesn't throw an error.

With this function, we can instead say
`get_nested_attr(resource_properties, "dialect.header", default=True)`,
optionally providing a default value. Similar to the built-in `getattr`.

<!-- Select quick/in-depth as necessary -->
This PR needs a quick review.

## Checklist

- [x] Added or updated tests
- [x] Updated documentation
- [x] Ran `just run-all`

Author: martonvago

seedcase_sprout/core/get_nested_attr.py

@@ -0,0 +1,51 @@
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def get_nested_attr(
+    base_object: Any, attributes: str, default: T | None = None
+) -> T | None:
+    """Returns the attribute specified by `attributes`.
+
+    Tries to resolve the chain of attributes against `base_object`. Returns None
+    or the specified default value if the attribute chain cannot be resolved.
+
+    Args:
+        base_object: The object to start resolving the attributes from.
+        attributes: The chain of attributes as a dot-separated string.
+        default: The default value to return if the attributes cannot be resolved.
+            Defaults to None.
+
+    Returns:
+        The value at the end of the attribute chain.
+
+    Raises:
+        ValueError: If the attribute chain contains an element that is not a valid
+            identifier.
+
+    Examples:
+        ```{python}
+        class Inner:
+            pass
+        class Middle:
+            inner: Inner = Inner()
+        class Outer:
+            middle: Middle = Middle()
+
+        get_nested_attr(Outer(), "middle.inner")
+        ```
+    """
+    attributes = attributes.split(".")
+    if any(not attribute.isidentifier() for attribute in attributes):
+        raise ValueError(
+            "`attributes` should contain valid identifiers separated by `.`."
+        )
+
+    try:
+        for attribute in attributes:
+            base_object = getattr(base_object, attribute)
+    except AttributeError:
+        return default
+
+    return default if base_object is None else base_object

tests/core/test_get_nested_attr.py

@@ -0,0 +1,94 @@
+from pytest import mark, raises
+
+from seedcase_sprout.core.get_nested_attr import get_nested_attr
+
+
+class D:
+    none: str | None = None
+    Number_1: int = 123
+
+
+d = D()
+
+
+class C:
+    d: D = d
+
+
+c = C()
+
+
+class B:
+    c: C = c
+
+
+b = B()
+
+
+class A:
+    b: B = b
+
+
+a = A()
+
+
+@mark.parametrize(
+    "nested_object,attributes,expected",
+    [
+        (a, "b.c.d", d),
+        (a, "b.c", c),
+        (a, "b", b),
+        (b, "c.d", d),
+        (c, "d", d),
+        (d, "Number_1", 123),
+        (d, "none", None),
+        (a, "a", None),
+        (a, "e", None),
+        (a, "b.c.d.e", None),
+        (a, "b.e.f.g", None),
+        (a, "b.c.d.e.f.g.h", None),
+    ],
+)
+def test_gets_nested_attribute(nested_object, attributes, expected):
+    """Should resolve an attribute chain and return the correct value."""
+    assert get_nested_attr(nested_object, attributes) == expected
+
+
+def test_returns_default_if_attribute_not_found():
+    """Should return the default value when the attribute chain cannot be resolved."""
+    assert get_nested_attr(a, "e", default="default") == "default"
+
+
+def test_returns_default_if_attribute_is_none():
+    """Should return the default value when the attribute exists and is None."""
+    assert get_nested_attr(d, "none", default="default") == "default"
+
+
+def test_ignores_default_if_attribute_found():
+    """Should ignore the default value when the attribute chain can be resolved."""
+    assert get_nested_attr(d, "Number_1", default=456) == 123
+
+
+@mark.parametrize(
+    "attributes",
+    [
+        "",
+        ".",
+        "...",
+        ".b",
+        "...b",
+        "b.",
+        "b...",
+        ".b.",
+        ".b.c.d",
+        "b..c",
+        ".b.c.d.",
+        "b,c,d",
+        "$",
+        "1",
+    ],
+)
+def test_throws_error_if_attribute_not_identifier(attributes):
+    """Should throw `ValueError` if the input doesn't contain valid identifiers."""
+    with raises(ValueError):
+        get_nested_attr(a, attributes)