confarg 0.0.1.dev2__py3-none-any.whl

confarg/_parse_env.py

@@ -0,0 +1,279 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Environment variable parsing for confarg."""
+
+from __future__ import annotations
+
+import json
+import warnings
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from confarg._errors import ConfargError, ConfargWarning
+from confarg._merge import DICT_DELETE, _accumulate_list_delete, _set_nested
+from confarg._types import (
+    _dict_kv,
+    _elem_type,
+    _is_callable,
+    _is_dict,
+    _is_frozenset,
+    _is_list,
+    _is_set,
+    _is_struct,
+    _is_struct_like,
+    _is_tuple,
+    _is_union,
+    _is_varlen_collection,
+    _resolve_type,
+    _StrToken,
+    _struct_fields,
+    _try_coerce,
+    _tuple_types,
+    _union_args_no_none,
+)
+
+
+def _resolve_env_parts(target: Any, parts: list[str]) -> tuple[list[str], Any]:
+    """Map env var parts to actual field names using case-insensitive matching.
+
+    Walks the type tree to find the correct casing for each path segment.
+    Falls back to lowercase when the type is not a dataclass (e.g. dict keys,
+    list indices).
+
+    Args:
+        target: The root target type.
+        parts: A list of env var path segments.
+
+    Returns:
+        A tuple of (resolved_parts, leaf_type) where resolved_parts has correct
+        casing and leaf_type is the resolved type of the final field (or None).
+
+    Raises:
+        ConfargError: If a part matches multiple field names at the same level.
+    """
+    resolved: list[str] = []
+    tp: Any = _resolve_type(target)
+
+    for part in parts:
+        name, tp = _match_env_part(tp, part)
+        resolved.append(name)
+
+    return resolved, tp
+
+
+def _match_env_part(tp: Any, part: str) -> tuple[str, Any]:
+    """Match a single env var part against the current type level.
+
+    Args:
+        tp: The current type being walked.
+        part: The env var path segment to match.
+
+    Returns:
+        A tuple of (resolved_name, next_type) where next_type may be None.
+    """
+    if tp is None:
+        return part.lower(), None
+
+    tp = _resolve_type(tp)
+
+    if _is_struct(tp):
+        flds = _struct_fields(tp)
+        matches = [name for name in flds if name.lower() == part.lower()]
+        if len(matches) > 1:
+            raise ConfargError(
+                f"Ambiguous env var segment {part!r}: matches multiple fields {matches} in {tp.__name__}."
+                " Check your dataclass definition for duplicate case-insensitive field names."
+            )
+        if len(matches) == 1:
+            return matches[0], flds[matches[0]]
+        return part.lower(), None
+
+    if _is_union(tp):
+        name_to_types: dict[str, list[Any]] = {}
+        for variant in _union_args_no_none(tp):
+            v = _resolve_type(variant)
+            if _is_struct(v):
+                flds = _struct_fields(v)
+                for fname in flds:
+                    if fname.lower() == part.lower():
+                        name_to_types.setdefault(fname, []).append(flds[fname])
+        if len(name_to_types) > 1:
+            raise ConfargError(
+                f"Ambiguous env var segment {part!r}: matches fields"
+                f" {sorted(name_to_types.keys())} across union variants."
+                " Use a more specific environment variable name or add a discriminator field."
+            )
+        if len(name_to_types) == 1:
+            name = next(iter(name_to_types))
+            types = name_to_types[name]
+            # Only return a concrete type when all variants agree; otherwise None (defer to construct)
+            ft = types[0] if all(t == types[0] for t in types[1:]) else None
+            return name, ft
+        return part.lower(), None
+
+    if _is_list(tp) or _is_set(tp) or _is_frozenset(tp):
+        return part.lower(), _elem_type(tp)
+
+    if _is_tuple(tp):
+        tt = _tuple_types(tp)
+        if tt is None:
+            return part.lower(), _elem_type(tp)
+        try:
+            idx = int(part)
+            if 0 <= idx < len(tt):
+                return part.lower(), tt[idx]
+        except ValueError:
+            pass
+        return part.lower(), None
+
+    if _is_dict(tp):
+        _, vt = _dict_kv(tp)
+        return part.lower(), vt
+
+    return part.lower(), None
+
+
+def _parse_env(
+    env: Mapping[str, str],
+    prefix: str,
+    separator: str,
+    target: Any,
+    config_flag: str = "config",
+) -> tuple[dict[str, Any], list[tuple[str, Path]]]:
+    """Parse environment variables into a nested dict matching the target type.
+
+    Variables are matched by prefix and split by separator into nested keys.
+    Field names are matched case-insensitively against the target type tree.
+    For non-dataclass targets, the value is stored under a ``__root__`` key.
+
+    A variable whose first segment (after stripping the prefix) matches
+    ``config_flag`` (case-insensitive) is treated as a sub-config file pointer:
+    the value is a file path, and the remaining segments form the subpath at
+    which the file's contents will be merged (e.g. ``CONFARG_CONFIG__DB=db.yaml``
+    merges ``db.yaml`` under the ``db`` key).
+
+    Args:
+        env: The environment variable mapping to scan.
+        prefix: Required prefix for relevant variables (empty string to match all).
+        separator: Separator used to split variable names into nested keys.
+        target: The target type, used to determine dataclass vs scalar handling.
+        config_flag: The magic segment name that marks a sub-config file pointer.
+
+    Returns:
+        A tuple of (data_dict, env_configs) where data_dict contains inline values
+        and env_configs is a list of (subpath, Path) pairs for deferred file loading.
+
+    Raises:
+        ConfargError: If an env var segment matches multiple field names.
+    """
+    data: dict[str, Any] = {}
+    env_configs: list[tuple[str, Path]] = []
+    is_struct = _is_struct_like(_resolve_type(target))
+
+    for orig_key, value in env.items():
+        key = orig_key
+        if prefix:
+            if not key.startswith(prefix):
+                continue
+            key = key[len(prefix) :]
+            key = key.removeprefix(separator)
+
+        parts = key.split(separator) if separator in key else [key]
+
+        # Config flag: CONFARG_CONFIG[__subpath]=file.yaml → defer to file loading
+        if parts[0].lower() == config_flag.lower():
+            subpath_parts = parts[1:]
+            if subpath_parts:
+                resolved_parts, _ = _resolve_env_parts(target, subpath_parts)
+                subpath = ".".join(resolved_parts)
+            else:
+                subpath = ""
+            env_configs.append((subpath, Path(value)))
+            continue
+
+        # Delete sentinel: FOO__BAR- deletes key BAR from FOO (dict-key deletion).
+        # FOO__ITEMS__1- deletes index 1 from FOO__ITEMS (list-index deletion).
+        if parts[-1].endswith("-") and len(parts[-1]) > 1:
+            raw_last = parts[-1][:-1]
+            try:
+                delete_idx = int(raw_last)
+                is_list_delete = True
+            except ValueError:
+                is_list_delete = False
+                delete_idx = -1
+
+            if is_list_delete:
+                parent_raw = parts[:-1]
+                if parent_raw:
+                    parent_parts, _ = _resolve_env_parts(target, parent_raw)
+                else:
+                    parent_parts = []
+                _accumulate_list_delete(data, parent_parts, delete_idx, orig_key)
+            else:
+                del_parts_raw = parts[:-1] + [raw_last]
+                del_parts, _ = _resolve_env_parts(target, del_parts_raw)
+                _set_nested(data, del_parts, DICT_DELETE)
+            continue
+
+        if not is_struct:
+            # For scalar targets, store under sentinel key
+            data["__root__"] = _try_coerce(_resolve_type(target), _StrToken(value))
+            continue
+
+        parts, ft = _resolve_env_parts(target, parts)
+        # Skip env vars whose first segment doesn't match a known field
+        root_tp = _resolve_type(target)
+        if _is_struct(root_tp) and parts[0] not in _struct_fields(root_tp):
+            known = sorted(_struct_fields(root_tp).keys())
+            warnings.warn(
+                f"Environment variable {orig_key!r} has no matching field"
+                f" (segment {parts[0]!r} not found in {root_tp.__name__})."
+                f" Known fields: {known}. The variable will be ignored.",
+                ConfargWarning,
+                stacklevel=3,
+            )
+            continue
+        if _is_union(root_tp):
+            struct_variants = [_resolve_type(v) for v in _union_args_no_none(root_tp) if _is_struct(_resolve_type(v))]
+            if struct_variants and not any(parts[0] in _struct_fields(v) for v in struct_variants):
+                all_fields = sorted({f for v in struct_variants for f in _struct_fields(v)})
+                warnings.warn(
+                    f"Environment variable {orig_key!r} has no matching field"
+                    f" (segment {parts[0]!r} not found in any union variant)."
+                    f" Known fields across variants: {all_fields}. The variable will be ignored.",
+                    ConfargWarning,
+                    stacklevel=3,
+                )
+                continue
+        if value.startswith(("[", "{")):
+            accepts_obj = value.startswith("{") and (
+                _is_struct(ft)
+                or _is_dict(ft)
+                or _is_callable(ft)
+                or (_is_union(ft) and any(_is_struct(_resolve_type(v)) for v in _union_args_no_none(ft)))
+            )
+            accepts_arr = value.startswith("[") and (
+                _is_varlen_collection(ft)
+                or _is_tuple(ft)
+                or (
+                    _is_union(ft)
+                    and any(
+                        _is_varlen_collection(_resolve_type(v)) or _is_tuple(_resolve_type(v))
+                        for v in _union_args_no_none(ft)
+                    )
+                )
+            )
+            if accepts_obj or accepts_arr:
+                try:
+                    parsed = json.loads(value)
+                    if isinstance(parsed, list | dict):
+                        _set_nested(data, parts, parsed)
+                        continue
+                except json.JSONDecodeError:
+                    pass
+        _set_nested(data, parts, _try_coerce(ft, _StrToken(value)))
+
+    return data, env_configs

confarg/_serialize.py

@@ -0,0 +1,206 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Serialization of dataclass instances to plain dicts."""
+
+from __future__ import annotations
+
+import enum
+from pathlib import Path
+from typing import Any
+
+from confarg._errors import ConfargError
+from confarg._types import (
+    TagPolicy,
+    _dict_kv,
+    _elem_type,
+    _is_callable,
+    _is_dict,
+    _is_frozenset,
+    _is_list,
+    _is_set,
+    _is_struct,
+    _is_tuple,
+    _is_union,
+    _resolve_type,
+    _StrToken,
+    _struct_fields,
+    _tuple_types,
+    _union_args_no_none,
+)
+from confarg.typedload._construct import _disambiguate_struct
+
+
+def _serialize(
+    tp: Any,
+    instance: Any,
+    path: str,
+    union_tag: str,
+    tag_policy: TagPolicy,
+) -> Any:
+    """Serialize a typed value to a plain dict/list/leaf structure.
+
+    Args:
+        tp: The declared type of the value.
+        instance: The value to serialize.
+        path: Dot-separated field path for diagnostics.
+        union_tag: The field name used as a discriminator tag in unions.
+        tag_policy: "auto" or "always".
+
+    Returns:
+        A JSON-compatible structure (dict, list, or leaf value).
+    """
+    tp = _resolve_type(tp)
+
+    if instance is None:
+        return None
+
+    if _is_callable(tp):
+        from confarg._callable import _serialize_callable
+
+        return _serialize_callable(instance)
+
+    if _is_union(tp):
+        return _serialize_union(tp, instance, path, union_tag, tag_policy)
+
+    if _is_struct(tp):
+        return _serialize_struct(tp, instance, path, union_tag, tag_policy)
+
+    if _is_list(tp):
+        et = _elem_type(tp)
+        return [_serialize(et, v, f"{path}[{i}]", union_tag, tag_policy) for i, v in enumerate(instance)]
+
+    if _is_set(tp) or _is_frozenset(tp):
+        et = _elem_type(tp)
+        items = [_serialize(et, v, path, union_tag, tag_policy) for v in instance]
+        return sorted(items, key=_sort_key)
+
+    if _is_tuple(tp):
+        return _serialize_tuple(tp, instance, path, union_tag, tag_policy)
+
+    if _is_dict(tp):
+        return _serialize_dict(tp, instance, path, union_tag, tag_policy)
+
+    return _serialize_leaf(tp, instance)
+
+
+def _serialize_struct(
+    tp: Any,
+    instance: Any,
+    path: str,
+    union_tag: str,
+    tag_policy: TagPolicy,
+) -> dict[str, Any]:
+    """Serialize a dataclass or plain-class instance to a dict."""
+    actual_tp = type(instance)
+    if actual_tp is not tp and _is_struct(actual_tp) and issubclass(actual_tp, tp):
+        out = _serialize_struct(actual_tp, instance, path, union_tag, tag_policy)
+        out[union_tag] = f"{actual_tp.__module__}.{actual_tp.__name__}"
+        return out
+    flds = _struct_fields(tp)
+    out: dict[str, Any] = {}
+    for name, ft in flds.items():
+        try:
+            value = getattr(instance, name)
+        except AttributeError:
+            raise ConfargError(
+                f"Field '{name}' is declared in {type(instance).__name__}.__init__"
+                f" but not accessible on the instance as self.{name}."
+                f" Plain classes must store every __init__ parameter as a same-named instance attribute."
+            ) from None
+        fp = f"{path}.{name}" if path else name
+        out[name] = _serialize(ft, value, fp, union_tag, tag_policy)
+    return out
+
+
+def _serialize_union(
+    tp: Any,
+    instance: Any,
+    path: str,
+    union_tag: str,
+    tag_policy: TagPolicy,
+) -> Any:
+    """Serialize a Union value, adding a class tag when needed."""
+    variant_tp = _find_variant_type(tp, instance)
+    if variant_tp is None:
+        return instance
+
+    serialized = _serialize(variant_tp, instance, path, union_tag, tag_policy)
+
+    if _is_struct(variant_tp) and isinstance(serialized, dict):
+        if tag_policy == "always" or _needs_tag(tp, serialized, union_tag):
+            serialized[union_tag] = f"{variant_tp.__module__}.{variant_tp.__name__}"
+
+    return serialized
+
+
+def _serialize_tuple(
+    tp: Any,
+    instance: Any,
+    path: str,
+    union_tag: str,
+    tag_policy: TagPolicy,
+) -> list[Any]:
+    """Serialize a tuple to a list."""
+    tt = _tuple_types(tp)
+    if tt is None:
+        et = _elem_type(tp)
+        return [_serialize(et, v, f"{path}[{i}]", union_tag, tag_policy) for i, v in enumerate(instance)]
+    return [
+        _serialize(et, v, f"{path}[{i}]", union_tag, tag_policy)
+        for i, (et, v) in enumerate(zip(tt, instance, strict=False))
+    ]
+
+
+def _serialize_dict(
+    tp: Any,
+    instance: Any,
+    path: str,
+    union_tag: str,
+    tag_policy: TagPolicy,
+) -> dict[Any, Any]:
+    """Serialize a typed dict."""
+    kt, vt = _dict_kv(tp)
+    return {
+        _serialize_leaf(kt, k): _serialize(vt, v, f"{path}.{k}", union_tag, tag_policy) for k, v in instance.items()
+    }
+
+
+def _serialize_leaf(tp: Any, value: Any) -> Any:
+    """Serialize a leaf value: Enum → .value, Path → str, float → float, else passthrough."""
+    if isinstance(value, enum.Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    if tp is float and isinstance(value, int) and not isinstance(value, bool):
+        return float(value)
+    if type(value) is _StrToken:
+        return str(value)
+    if isinstance(value, type):
+        return f"{value.__module__}.{value.__qualname__}"
+    return value
+
+
+def _find_variant_type(tp: Any, instance: Any) -> Any | None:
+    """Find which Union variant matches the instance's type."""
+    args = _union_args_no_none(tp)
+    for arg in args:
+        arg_r = _resolve_type(arg)
+        if isinstance(instance, arg_r):
+            return arg_r
+    return None
+
+
+def _needs_tag(tp: Any, serialized_data: dict[str, Any], union_tag: str) -> bool:
+    """Check if a class tag is needed by running disambiguation on the serialized data."""
+    struct_vars = [v for v in _union_args_no_none(tp) if _is_struct(_resolve_type(v))]
+    if len(struct_vars) <= 1:
+        return False
+    matches = _disambiguate_struct(struct_vars, serialized_data, union_tag)
+    return len(matches) != 1
+
+
+def _sort_key(value: Any) -> tuple[str, str]:
+    """Sort key for heterogeneous set/frozenset serialization."""
+    return (type(value).__name__, str(value))