✨ feat: get_field (#39)

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

Author: nstarman

src/dataclassish/__init__.py

@@ -8,16 +8,17 @@
     # Submodules
     "converters",
     "flags",
-    # Dataclass API
-    "DataclassInstance",
+    # functions
     "replace",
     "fields",
     "asdict",
     "astuple",
-    # Extensions
+    "get_field",
     "field_keys",
     "field_values",
     "field_items",
+    # Classes
+    "DataclassInstance",
     "F",
 ]
 
@@ -29,6 +30,7 @@
     field_keys,
     field_values,
     fields,
+    get_field,
     replace,
 )
 from ._src.types import DataclassInstance, F

src/dataclassish/_src/api.py

@@ -7,6 +7,7 @@
     "asdict",
     "astuple",
     # Extensions
+    "get_field",
     "field_keys",
     "field_values",
     "field_items",
@@ -50,6 +51,12 @@ def astuple(obj: Any, /) -> tuple[Any, ...]:
 # Extensions
 
 
+@dispatch.abstract  # type: ignore[misc]
+def get_field(obj: Any, field_name: str, /) -> Any:
+    """Get the value of a field from an object."""
+    raise NotImplementedError  # pragma: no cover
+
+
 @dispatch.abstract  # type: ignore[misc]
 def field_keys(obj: Any, /) -> tuple[str, ...]:
     """Return the field names from the `dataclassish.fields`."""

src/dataclassish/_src/register_base.py

@@ -11,6 +11,31 @@
 K = TypeVar("K")
 V = TypeVar("V")
 
+# ===================================================================
+
+
+@dispatch  # type: ignore[misc]
+def get_field(obj: Any, k: str, /) -> Any:
+    """Get a field of an object by name.
+
+    This default implementation is just to call `getattr`.
+
+    Examples
+    --------
+    >>> from dataclassish import get_field
+
+    >>> class Point:
+    ...     def __init__(self, x, y):
+    ...         self.x = x
+    ...         self.y = y
+
+    >>> p = Point(1.0, 2.0)
+    >>> get_field(p, "x")
+    1.0
+
+    """
+    return getattr(obj, k)
+
 
 # ===================================================================
 # Field keys

src/dataclassish/_src/register_dataclass.py

@@ -16,6 +16,31 @@
 
 from .types import DataclassInstance, F
 
+# ===================================================================
+
+
+@dispatch  # type: ignore[misc]
+def get_field(obj: DataclassInstance, k: str, /) -> Any:
+    """Get a field of a dataclass instance by name.
+
+    Examples
+    --------
+    >>> from dataclasses import dataclass
+    >>> from dataclassish import get_field
+
+    >>> @dataclass
+    ... class Point:
+    ...     x: float
+    ...     y: float
+
+    >>> p = Point(1.0, 2.0)
+    >>> get_field(p, "x")
+    1.0
+
+    """
+    return getattr(obj, k)
+
+
 # ===================================================================
 # Replace
 
@@ -51,7 +76,7 @@ def _recursive_replace_dataclass_helper(
     if isinstance(v, F):
         out = v.value
     elif isinstance(v, Mapping):
-        out = replace(getattr(obj, k), v)
+        out = replace(get_field(obj, k), v)
     else:
         out = v
     return out
@@ -87,6 +112,23 @@ def replace(obj: DataclassInstance, fs: Mapping[str, Any], /) -> DataclassInstan
     PointofPoints(a=Point(x={'thing': 5.0}, y=2.0),
                   b=Point(x=3.0, y=4.0))
 
+    This also works on mixed-type structures, e.g. a dictionary of dataclasses.
+
+    >>> p = {"a": Point(1.0, 2.0), "b": Point(3.0, 4.0)}
+    >>> replace(p, {"a": {"x": 5.0}, "b": {"y": 6.0}})
+    {'a': Point(x=5.0, y=2.0), 'b': Point(x=3.0, y=6.0)}
+
+    Or a dataclass of dictionaries.
+
+    >>> @dataclass
+    ... class Object:
+    ...     a: dict[str, Any]
+    ...     b: dict[str, Any]
+
+    >>> p = Object({"a": 1, "b": 2}, {"c": 3, "d": 4})
+    >>> replace(p, {"a": {"b": 5}, "b": {"c": 6}})
+    Object(a={'a': 1, 'b': 5}, b={'c': 6, 'd': 4})
+
     """
     kwargs = {k: _recursive_replace_dataclass_helper(obj, k, v) for k, v in fs.items()}
     return _dataclass_replace(obj, **kwargs)

src/dataclassish/_src/register_mapping.py

@@ -10,6 +10,25 @@
 
 from .types import F
 
+# ===================================================================
+
+
+@dispatch(precedence=1)  # type: ignore[misc]
+def get_field(obj: Mapping[Hashable, Any], k: Hashable, /) -> Any:
+    """Get a field of a mapping by key.
+
+    Examples
+    --------
+    >>> from dataclassish import get_field
+
+    >>> p = {"a": 1, "b": 2.0, "c": "3"}
+    >>> get_field(p, "a")
+    1
+
+    """
+    return obj[k]
+
+
 # ===================================================================
 # Replace
 
@@ -54,7 +73,7 @@ def _recursive_replace_mapping_helper(
     if isinstance(v, F):  # Field, stop here.
         out = v.value
     elif isinstance(v, Mapping):  # more to replace, recurse.
-        out = replace(obj[k], v)
+        out = replace(get_field(obj, k), v)
     else:  # nothing to replace, keep the value.
         out = v
     return out
@@ -82,6 +101,18 @@ def replace(
     >>> replace(p, {"c": F({"aa": 6, "bb": {"d": 7}})})
     {'a': 1, 'b': 2.0, 'c': {'aa': 6, 'bb': {'d': 7}}}
 
+    This also works on mixed-type structures, e.g. a dataclass of of dictionaries.
+
+    >>> from dataclasses import dataclass
+    >>> @dataclass
+    ... class Object:
+    ...     a: dict[str, Any]
+    ...     b: dict[str, Any]
+
+    >>> p = Object({"a": 1, "b": 2}, {"c": 3, "d": 4})
+    >>> replace(p, {"a": {"b": 5}, "b": {"c": 6}})
+    Object(a={'a': 1, 'b': 5}, b={'c': 6, 'd': 4})
+
     """
     # Recursively replace the fields
     kwargs = {k: _recursive_replace_mapping_helper(obj, k, v) for k, v in fs.items()}