PathBridge 0.2.0__tar.gz → 0.3.0__tar.gz

{pathbridge-0.2.0 → pathbridge-0.3.0}/.gitignore

@@ -17,4 +17,6 @@ TODO.rst
 .pytest_cache/
 htmlcov/
 __pycache__/
-_version.py
+_version.py
+.claude/settings.local.json
+CLAUDE.local.md

{pathbridge-0.2.0 → pathbridge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PathBridge
-Version: 0.2.0
+Version: 0.3.0
 Summary: Translate validator error locations back to your application's schema paths and emit structured errors
 Project-URL: Homepage, https://github.com/pilosus/pathbridge
 Project-URL: Repository, https://github.com/pilosus/pathbridge
@@ -25,6 +25,7 @@ Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: xsdata[cli]>=26.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # PathBridge
@@ -78,7 +79,7 @@ errors = to_marshmallow([(loc, "Invalid phone")], compiled)
 `pathbridge.extras` provides helper utilities for generating rules from your
 converter:
 
-- `make_shape(...)`: build a truthy sample facade object.
+- `make_shape(...)`: build a populated sample facade object.
 - `build_rules(...)`: trace a sample conversion and produce `Destination -> Facade`
   mapping rules.
 
@@ -157,3 +158,22 @@ print(errors)
 #   }
 # }
 ```
+
+### Custom shape defaults
+
+`make_shape(...)` accepts `type_defaults` so you can override generated defaults
+for specific types:
+
+```python
+from decimal import Decimal
+
+shape = make_shape(
+    Facade,
+    list_len=2,
+    type_defaults={
+        str: "sample",
+        int: 42,
+        Decimal: Decimal("1.23"),
+    },
+)
+```

{pathbridge-0.2.0 → pathbridge-0.3.0}/README.md

@@ -49,7 +49,7 @@ errors = to_marshmallow([(loc, "Invalid phone")], compiled)
 `pathbridge.extras` provides helper utilities for generating rules from your
 converter:
 
-- `make_shape(...)`: build a truthy sample facade object.
+- `make_shape(...)`: build a populated sample facade object.
 - `build_rules(...)`: trace a sample conversion and produce `Destination -> Facade`
   mapping rules.
 
@@ -128,3 +128,22 @@ print(errors)
 #   }
 # }
 ```
+
+### Custom shape defaults
+
+`make_shape(...)` accepts `type_defaults` so you can override generated defaults
+for specific types:
+
+```python
+from decimal import Decimal
+
+shape = make_shape(
+    Facade,
+    list_len=2,
+    type_defaults={
+        str: "sample",
+        int: 42,
+        Decimal: Decimal("1.23"),
+    },
+)
+```

{pathbridge-0.2.0 → pathbridge-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "PathBridge"
-version = "0.2.0"
+version = "0.3.0"
 description = "Translate validator error locations back to your application's schema paths and emit structured errors"
 readme = "README.md"
 license = "MIT"
@@ -34,6 +34,7 @@ dev = [
     "pytest-cov>=4.0",
     "mypy>=1.0",
     "ruff>=0.4",
+    "xsdata[cli]>=26.0",
 ]
 
 [project.urls]

pathbridge-0.3.0/src/pathbridge/extras/shaper.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import contextlib
+import dataclasses
+import datetime as dt
+import inspect
+import sys
+import types
+import typing as t
+from decimal import Decimal
+from enum import Enum
+from uuid import UUID
+
+T = t.TypeVar("T")
+_NO_DEFAULT = object()
+TypeDefaultMapping = dict[t.Any, t.Any | t.Callable[[], t.Any]]
+
+DEFAULT_TYPE_DEFAULTS: TypeDefaultMapping = {
+    str: "",
+    int: 0,
+    float: 0.0,
+    bool: True,
+    Decimal: Decimal("0"),
+    dt.date: dt.date(1970, 1, 1),
+    dt.datetime: dt.datetime(1970, 1, 1),
+    UUID: UUID(int=0),
+}
+
+
+def _is_dataclass_type(tp: t.Any) -> t.TypeGuard[type[t.Any]]:
+    return inspect.isclass(tp) and dataclasses.is_dataclass(tp)
+
+
+def _dataclass_fields(cls: type[t.Any]) -> tuple[dataclasses.Field[t.Any], ...]:
+    return dataclasses.fields(cls)
+
+
+def _strip_annotated(tp: t.Any) -> t.Any:
+    origin = t.get_origin(tp)
+    if origin is t.Annotated:
+        args = t.get_args(tp)
+        if args:
+            return args[0]
+    return tp
+
+
+def _resolve_type_hints(cls: type[t.Any]) -> dict[str, t.Any]:
+    module = sys.modules.get(cls.__module__)
+    module_ns: dict[str, t.Any] = vars(module).copy() if module is not None else {}
+    try:
+        return t.get_type_hints(
+            cls,
+            globalns=module_ns,
+            localns=module_ns,
+            include_extras=True,
+        )
+    except Exception:
+        return {f.name: f.type for f in _dataclass_fields(cls)}
+
+
+def _default_for_custom_scalar(origin: t.Any) -> t.Any:
+    if not inspect.isclass(origin):
+        return _NO_DEFAULT
+
+    cls_name = origin.__name__
+
+    # Factory methods are often the safest constructor path for xsdata wrappers.
+    from_string = getattr(origin, "from_string", None)
+    if callable(from_string):
+        for literal in ("1970-01-01", "1970-01-01T00:00:00", "00:00:00"):
+            with contextlib.suppress(Exception):
+                return from_string(literal)
+
+    from_date = getattr(origin, "from_date", None)
+    if callable(from_date):
+        with contextlib.suppress(Exception):
+            return from_date(dt.date(1970, 1, 1))
+
+    from_datetime = getattr(origin, "from_datetime", None)
+    if callable(from_datetime):
+        with contextlib.suppress(Exception):
+            return from_datetime(dt.datetime(1970, 1, 1))
+
+    # Common constructor style used by xsdata scalar date/time wrappers.
+    if cls_name in {"XmlDate", "XmlDateTime", "XmlTime"} or cls_name.startswith("Xml"):
+        for args in (
+            (),
+            (1970, 1, 1),
+            (1970, 1, 1, 0, 0, 0),
+            (0, 0, 0),
+        ):
+            with contextlib.suppress(Exception):
+                return origin(*args)
+
+    return _NO_DEFAULT
+
+
+def _mapping_default(
+    tp: t.Any,
+    origin: t.Any,
+    type_defaults: TypeDefaultMapping,
+) -> t.Any:
+    for key in (tp, origin):
+        if key in type_defaults:
+            configured = type_defaults[key]
+            return configured() if callable(configured) else configured
+    return _NO_DEFAULT
+
+
+def _is_optional(tp: t.Any) -> tuple[bool, t.Any]:
+    """Return (is_optional, inner_type)."""
+    tp = _strip_annotated(tp)
+    origin = t.get_origin(tp)
+    if origin in (t.Union, types.UnionType):  # Optional[T] is Union[T, NoneType]
+        args = [a for a in t.get_args(tp) if a is not type(None)]
+        if args:
+            return True, args[0]
+    return False, tp
+
+
+def _is_list(tp: t.Any) -> tuple[bool, t.Any]:
+    tp = _strip_annotated(tp)
+    origin = t.get_origin(tp)
+    if origin in (list, list):
+        args = t.get_args(tp)
+        return True, (args[0] if args else t.Any)
+    return False, tp
+
+
+def _is_dict(tp: t.Any) -> tuple[bool, t.Any, t.Any]:
+    tp = _strip_annotated(tp)
+    origin = t.get_origin(tp)
+    if origin in (dict, dict):
+        args = t.get_args(tp)
+        key_t = args[0] if args else t.Any
+        val_t = args[1] if len(args) > 1 else t.Any
+        return True, key_t, val_t
+    return False, tp, tp
+
+
+def _safe_first_enum(enum_cls: type[Enum]) -> Enum:
+    try:
+        return next(iter(enum_cls))
+    except StopIteration:
+        raise ValueError(f"Enum {enum_cls!r} has no members") from None
+
+
+def _default_for_type(tp: t.Any) -> t.Any:
+    """Produce a non-empty, truthy default for a scalar-ish type."""
+    return _default_for_type_with_mapping(tp, DEFAULT_TYPE_DEFAULTS)
+
+
+def _default_for_type_with_mapping(
+    tp: t.Any,
+    type_defaults: TypeDefaultMapping,
+) -> t.Any:
+    """Produce a default scalar value using built-ins and user overrides."""
+    tp = _strip_annotated(tp)
+    origin = t.get_origin(tp) or tp
+
+    mapped = _mapping_default(tp, origin, type_defaults)
+    if mapped is not _NO_DEFAULT:
+        return mapped
+
+    if inspect.isclass(origin) and issubclass(origin, Enum):
+        return _safe_first_enum(origin)
+    custom_default = _default_for_custom_scalar(origin)
+    if custom_default is not _NO_DEFAULT:
+        return custom_default
+    return 0
+
+
+def _apply_overrides(obj: t.Any, overrides: dict[str, t.Any]) -> t.Any:
+    """
+    Apply dotted-path overrides like:
+      "foo.bar[2].baz": 42
+    Works with dataclasses, lists, and dicts.
+    """
+    for path, value in overrides.items():
+        parts = [p for p in path.split(".") if p]
+        target = obj
+        for i, token in enumerate(parts):
+            # handle [idx] suffix
+            name, idx = token, None
+            if "[" in token and token.endswith("]"):
+                name, idx = (
+                    token[: token.index("[")],
+                    int(token[token.index("[") + 1 : -1]),
+                )
+
+            if i == len(parts) - 1:
+                # set leaf
+                if idx is None:
+                    if dataclasses.is_dataclass(target):
+                        setattr(target, name, value)
+                    elif isinstance(target, dict):
+                        target[name] = value
+                    else:
+                        setattr(target, name, value)
+                else:
+                    seq = getattr(target, name)
+                    seq[idx] = value
+                break
+
+            # descend
+            if dataclasses.is_dataclass(target):
+                target = getattr(target, name)
+            elif isinstance(target, dict):
+                target = target[name]
+            else:
+                target = getattr(target, name)
+
+            if idx is not None:
+                target = target[idx]
+    return obj
+
+
+def _shape_for_type(
+    tp: t.Any,
+    *,
+    list_len: int,
+    seen: set[type],
+    type_defaults: TypeDefaultMapping,
+) -> t.Any:
+    tp = _strip_annotated(tp)
+    is_opt, inner = _is_optional(tp)
+    if is_opt:
+        tp = inner
+
+    is_list, elem_t = _is_list(tp)
+    if is_list:
+        return [
+            _shape_for_type(
+                elem_t,
+                list_len=list_len,
+                seen=seen,
+                type_defaults=type_defaults,
+            )
+            for _ in range(list_len)
+        ]
+
+    is_dict, _key_t, _val_t = _is_dict(tp)
+    if is_dict:
+        return {}
+
+    origin = t.get_origin(tp)
+    if origin in (t.Union, types.UnionType):
+        args = t.get_args(tp)
+        if args:
+            return _shape_for_type(
+                args[0],
+                list_len=list_len,
+                seen=seen,
+                type_defaults=type_defaults,
+            )
+
+    resolved = origin or tp
+    if _is_dataclass_type(resolved):
+        return _shape_dataclass(
+            resolved,
+            list_len=list_len,
+            overrides=None,
+            seen=seen,
+            type_defaults=type_defaults,
+        )
+    return _default_for_type_with_mapping(resolved, type_defaults)
+
+
+def _shape_dataclass(
+    cls: type[T],
+    *,
+    list_len: int,
+    overrides: dict[str, t.Any] | None,
+    seen: set[type],
+    type_defaults: TypeDefaultMapping,
+) -> T:
+    if cls in seen:
+        # stop infinite recursion; build minimal
+        minimal_kwargs: dict[str, t.Any] = {}
+        for f in _dataclass_fields(cls):
+            minimal_kwargs[f.name] = None
+        return cls(**minimal_kwargs)
+    seen.add(cls)
+
+    try:
+        type_hints = _resolve_type_hints(cls)
+        kwargs: dict[str, t.Any] = {}
+        for f in _dataclass_fields(cls):
+            field_type = type_hints.get(f.name, f.type)
+            kwargs[f.name] = _shape_for_type(
+                field_type,
+                list_len=list_len,
+                seen=seen,
+                type_defaults=type_defaults,
+            )
+
+        inst = cls(**kwargs)
+        if overrides:
+            _apply_overrides(inst, overrides)
+        return inst
+    finally:
+        seen.remove(cls)
+
+
+def make_shape(
+    spec: type[T] | T | t.Callable[[], T],
+    *,
+    list_len: int = 1,
+    overrides: dict[str, t.Any] | None = None,
+    type_defaults: TypeDefaultMapping | None = None,
+) -> T:
+    """
+    Construct a 'truthy' instance for the given facade class/instance/factory.
+
+    - spec: dataclass class, an instance (will be cloned shallowly), or a zero-arg factory
+    - list_len: default length for list fields
+    - overrides: dotted-path -> value to force (supports [index])
+    - type_defaults: optional mapping `{type: default_or_factory}` to override
+      built-in scalar defaults.
+
+    Heuristics:
+      - dataclasses: recursively instantiate with non-empty defaults
+      - Optional[T]: pick T with a non-empty value
+      - enums: pick first member
+      - str: ""; int: 0; Decimal: 0; bool: True; date: 1970-01-01
+      - lists: [truthy(T) for _ in range(list_len)]
+    """
+    resolved_type_defaults: TypeDefaultMapping = dict(DEFAULT_TYPE_DEFAULTS)
+    if type_defaults:
+        resolved_type_defaults.update(type_defaults)
+
+    if inspect.isclass(spec):
+        if dataclasses.is_dataclass(spec):
+            base = _shape_dataclass(
+                t.cast(type[T], spec),
+                list_len=list_len,
+                overrides=overrides,
+                seen=set(),
+                type_defaults=resolved_type_defaults,
+            )
+        else:
+            raise TypeError(
+                "make_shape expects a dataclass class/instance or a zero-arg factory"
+            )
+    elif dataclasses.is_dataclass(spec):
+        # already an instance: (re)apply overrides and return
+        base = t.cast(T, spec)
+        if overrides:
+            _apply_overrides(base, overrides)
+    elif callable(spec):
+        base = spec()
+    else:
+        raise TypeError(
+            "make_shape expects a dataclass class/instance or a zero-arg factory"
+        )
+    return base

{pathbridge-0.2.0 → pathbridge-0.3.0}/src/pathbridge/extras/trace.py

@@ -4,6 +4,7 @@ import contextlib
 import dataclasses
 import enum
 import inspect
+import re
 import types
 import typing as t
 
@@ -20,6 +21,7 @@ def trace_converter(
     converter: t.Callable[[t.Any], t.Any],
     lift: t.Iterable[str] | None = None,
     root_tag: str = "root",
+    destination_prefix: str | None = None,
 ) -> TraceContext:
     """
     Context manager that enables tracing patches. Yields a callable:
@@ -31,6 +33,8 @@ def trace_converter(
             Accepts simple names resolvable in converter's globals, or fully
             qualified 'pkg.mod:func' strings.
     - root_tag: starting facade segment, e.g. "mtr"
+    - destination_prefix: optional prefix for destination XML path segments,
+            e.g. "MTR" to render "MTR:ElementName[1]"
 
     Returns a context manager. Inside it, call the yielded function with a *facade*
     instance (your shape); it returns (result_object, rules_dict).
@@ -40,6 +44,7 @@ def trace_converter(
         converter=converter,
         lift=tuple(lift or ()),
         root_tag=root_tag,
+        destination_prefix=destination_prefix,
     )
 
 
@@ -50,6 +55,7 @@ def build_rules(
     shape: t.Any,
     lift: t.Iterable[str] | None = None,
     root_tag: str = "root",
+    destination_prefix: str | None = None,
 ) -> RawRulesMapT:
     """
     Build a destination-to-facade rules map from one traced conversion run.
@@ -68,12 +74,18 @@ def build_rules(
         lift: Optional helper function names that should preserve path tags
             (`"name"` or `"pkg.mod:func"`).
         root_tag: Root token used as the facade-path prefix in recorded rules.
+        destination_prefix: Optional destination segment prefix
+            (e.g. `"MTR"` -> `MTR:Element[1]`).
 
     Returns:
         Mapping of destination paths to facade paths (`DEST -> FACADE`).
     """
     with trace_converter(
-        model_module=model_module, converter=converter, lift=lift, root_tag=root_tag
+        model_module=model_module,
+        converter=converter,
+        lift=lift,
+        root_tag=root_tag,
+        destination_prefix=destination_prefix,
     ) as run:
         _, rules = run(shape)
         return rules
@@ -87,11 +99,13 @@ def build_rules(
 U = t.TypeVar("U")
 InitCallable = t.Callable[..., None]
 LiftRecord = tuple[types.ModuleType, str, t.Callable[..., t.Any]]
+LeafRecord = tuple[list[str], str]
 ParentStack = tuple[tuple[str, int], ...]
 CounterKey = tuple[ParentStack, str]
+NodeKey = tuple[ParentStack, str, str]
+TRACER_LEAVES_ATTR = "__tracer_leaves__"
 
 
-# A minimal tag that carries a source facade path alongside a value.
 class Tagged(t.Generic[U]):
     __slots__ = ("value", "path")
 
@@ -103,30 +117,17 @@ class Tagged(t.Generic[U]):
         return f"Tagged({self.value!r}, {self.path})"
 
 
-def _is_scalar(x: t.Any) -> bool:
-    return not dataclasses.is_dataclass(x) and not isinstance(x, (list, tuple, dict))
-
-
 def _wrap_src(obj: t.Any, path: str) -> t.Any:
-    """Wrap a facade object with proxies that yield Tagged leaves."""
-    # dataclass -> attribute-proxy
     if dataclasses.is_dataclass(obj):
         return _DataclassProxy(obj, path)
-    # list/tuple -> collection of proxies
     if isinstance(obj, (list, tuple)):
         return type(obj)(_wrap_src(v, f"{path}[{i}]") for i, v in enumerate(obj))
-    # dict -> proxy each value
     if isinstance(obj, dict):
         return {k: _wrap_src(v, f"{path}/{k}") for k, v in obj.items()}
-    # leaf -> Tagged
     return Tagged(obj, path)
 
 
 class _DataclassProxy:
-    """
-    Lightweight facade proxy that mirrors a dataclass and returns Tagged leaves.
-    """
-
     __slots__ = ("__obj", "__path")
 
     def __init__(self, obj: t.Any, path: str) -> None:
@@ -136,114 +137,128 @@ class _DataclassProxy:
     def __getattr__(self, name: str) -> t.Any:
         obj = object.__getattribute__(self, "_DataclassProxy__obj")
         path = object.__getattribute__(self, "_DataclassProxy__path")
-        val = getattr(obj, name)
-        # Normalize to dotted attr path on facade side
-        sub_path = f"{path}/{name}"
-        return _wrap_src(val, sub_path)
-
-    # for explicit indexing on proxied lists nested under attributes, users will get
-    # real list proxies returned from __getattr__, so normal indexing works.
-
-
-# Destination path builders (xsdata-friendly but generic)
+        return _wrap_src(getattr(obj, name), f"{path}/{name}")
 
 
 def _xml_class_name(cls: type) -> str:
-    """Try xsdata's Meta.name; otherwise use class name."""
     meta = getattr(cls, "Meta", None)
     return getattr(meta, "name", cls.__name__)
 
 
 def _xml_field_name(cls: type, py_name: str) -> str:
-    """Try xsdata field metadata 'name'; otherwise Python field name."""
     fld = cls.__dataclass_fields__[py_name]  # type: ignore[attr-defined]
     meta = fld.metadata or {}
     return t.cast(str, meta.get("name", py_name))
 
 
-class _TracerState:
-    def __init__(self, root_tag: str) -> None:
-        self.root_tag = root_tag
-        # stack of (xml_element_name, index)
-        self.stack: list[tuple[str, int]] = []
-        # per-parent-element counters to assign 1-based [n] to siblings
-        self.counters: dict[CounterKey, int] = {}
-        # collected rules: DEST -> FACADE
-        self.rules: RawRulesMapT = {}
-
-    # ---- stack management ----
-
-    def push(self, name: str) -> int:
-        parent = tuple(self.stack)
-        key = (parent, name)
-        idx = self.counters.get(key, 0) + 1  # 1-based for DEST
-        self.counters[key] = idx
-        self.stack.append((name, idx))
-        return idx
-
-    def pop(self) -> None:
-        self.stack.pop()
-
-    # ---- path formatting ----
-
-    def current_prefix(self) -> str:
-        # e.g., "MTR:MTR[1]/MTR:Sa103S[2]" without namespaces, generic:
-        if not self.stack:
-            return _escape_step(self.root_tag) + "[1]"
-        return "/".join(f"{_escape_step(name)}[{idx}]" for (name, idx) in self.stack)
-
-    def add_leaf(self, field_xml_name: str, src_path: str) -> None:
-        # Build full destination path including the leaf element
-        dest = self.current_prefix() + f"/{_escape_step(field_xml_name)}[1]"
-        # rules map DEST -> FACADE (src_path is in facade token format)
-        # Keep the last writer if duplicates occur (first-win/last-win both OK)
-        self.rules[dest] = src_path
-
-
 def _escape_step(name: str) -> str:
-    """Escape a step name safely for later regex compilation (kept literal here)."""
-    # We keep it as-is; compiler will escape and normalize.
     return name
 
 
-def _record_scalar_field(
-    state: _TracerState, cls: type, field_name: str, value: t.Any
-) -> None:
-    if isinstance(value, Tagged):
-        xml_field = _xml_field_name(cls, field_name)
-        state.add_leaf(xml_field, value.path)
+def _format_step(name: str, destination_prefix: str | None) -> str:
+    escaped = _escape_step(name)
+    if destination_prefix:
+        return f"{destination_prefix}:{escaped}"
+    return escaped
+
+
+def _normalize_xml_name(name: str) -> str:
+    return re.sub(r"\W+", "", name).upper()
+
+
+def _nested_segment_name(parent_cls: type, field_name: str, child_value: t.Any) -> str:
+    field_xml = _xml_field_name(parent_cls, field_name)
+    child_xml = _xml_class_name(type(child_value))
+    if _normalize_xml_name(field_xml) == _normalize_xml_name(child_xml):
+        return child_xml
+    return field_xml
+
+
+def _get_leaves(obj: t.Any) -> list[LeafRecord]:
+    leaves = getattr(obj, TRACER_LEAVES_ATTR, None)
+    if isinstance(leaves, list):
+        return t.cast(list[LeafRecord], leaves)
+    return []
+
 
+def _unwrap_field_value(
+    cls: type,
+    field_name: str,
+    value: t.Any,
+) -> tuple[t.Any, list[LeafRecord]]:
+    field_xml_name = _xml_field_name(cls, field_name)
+
+    if isinstance(value, Tagged):
+        return value.value, [([field_xml_name], value.path)]
 
-def _record_list_field(
-    state: _TracerState, cls: type, field_name: str, value: t.Any
-) -> None:
-    # If the list elements are Tagged scalars, record per index.
     if isinstance(value, (list, tuple)):
-        for _, elem in enumerate(value):
-            if isinstance(elem, Tagged):
-                xml_field = _xml_field_name(cls, field_name)
-                # Temporarily push the list item context to compute [i+1]
-                state.push(xml_field)
-                # Leaf under this item
-                state.add_leaf(
-                    _xml_field_name(cls, field_name), elem.path
-                )  # element name reused
-                state.pop()
+        unwrapped_items: list[t.Any] = []
+        leaves: list[LeafRecord] = []
+        for item in value:
+            if isinstance(item, Tagged):
+                # Keep two steps to preserve item index in generated destination path.
+                leaves.append(([field_xml_name, field_xml_name], item.path))
+                unwrapped_items.append(item.value)
+            else:
+                unwrapped_items.append(item)
+        if isinstance(value, tuple):
+            return tuple(unwrapped_items), leaves
+        return unwrapped_items, leaves
 
+    return value, []
 
-# Monkey-patch machinery
 
+def _split_facade_path(path: str) -> list[str]:
+    return [part for part in path.split("/") if part]
 
-class TraceContext:
-    """
-    Context manager that patches destination dataclasses' __init__ and enum lookups,
-    and (optionally) lifts helper functions to preserve Tagged values.
 
-    Usage:
-        with trace_converter(model_module=..., converter=..., ...) as run:
-            result, rules = run(facade_shape)
-    """
+def _leaves_to_rules(
+    leaves: list[LeafRecord], destination_prefix: str | None
+) -> RawRulesMapT:
+    rules: RawRulesMapT = {}
+    counters: dict[CounterKey, int] = {}
+    nodes: dict[NodeKey, int] = {}
+
+    for segments, src_path in leaves:
+        if not segments:
+            continue
+
+        src_parts = _split_facade_path(src_path)
+        stack: list[tuple[str, int]] = []
+        rendered_parts: list[str] = []
+        for depth, name in enumerate(segments):
+            if depth < len(src_parts):
+                src_prefix = "/".join(src_parts[: depth + 1])
+            else:
+                src_prefix = f"{src_path}#d{depth}"
+
+            parent = tuple(stack)
+            node_key = (parent, name, src_prefix)
+            if node_key in nodes:
+                idx = nodes[node_key]
+            else:
+                counter_key = (parent, name)
+                idx = counters.get(counter_key, 0) + 1
+                counters[counter_key] = idx
+                nodes[node_key] = idx
+
+            stack.append((name, idx))
+            rendered_parts.append(f"{_format_step(name, destination_prefix)}[{idx}]")
+
+            # Include intermediate parent path mappings when facade depth exists.
+            # Depth 0 is the root object and usually too broad to be useful.
+            if depth > 0 and depth < len(src_parts) - 1:
+                parent_dest = "/".join(rendered_parts)
+                parent_src = "/".join(src_parts[: depth + 1])
+                if parent_dest not in rules:
+                    rules[parent_dest] = parent_src
+
+        rules["/".join(rendered_parts)] = src_path
+
+    return rules
 
+
+class TraceContext:
     def __init__(
         self,
         *,
@@ -251,19 +266,19 @@ class TraceContext:
         converter: t.Callable[[t.Any], t.Any],
         lift: tuple[str, ...],
         root_tag: str,
+        destination_prefix: str | None,
     ) -> None:
         self.model_module = model_module
         self.converter = converter
         self.lift = lift
         self.root_tag = root_tag
+        self.destination_prefix = destination_prefix
 
         self._orig_inits: dict[type, InitCallable] = {}
-        self._patched_classes: list[type] = []
         self._orig_enummeta_getitem: (
             t.Callable[[type[enum.Enum], t.Any], t.Any] | None
         ) = None
         self._lifted: list[LiftRecord] = []
-        self._state = _TracerState(root_tag=root_tag)
 
     def __enter__(self) -> t.Callable[[t.Any], tuple[t.Any, RawRulesMapT]]:
         self._patch_dataclasses()
@@ -282,27 +297,38 @@ class TraceContext:
         self._restore_enum_meta()
         self._restore_dataclasses()
 
-    # ---- core run ----
-
     def _run(self, facade_root: t.Any) -> tuple[t.Any, RawRulesMapT]:
-        # Wrap the facade so reads return Tagged (or proxies)
         proxied = _wrap_src(facade_root, self.root_tag)
-        # Execute converter under a fresh state
-        self._state = _TracerState(root_tag=self.root_tag)
         result = self.converter(proxied)
-        return result, dict(self._state.rules)
-
-    # ---- patch dataclasses ----
+        if dataclasses.is_dataclass(result):
+            return result, _leaves_to_rules(
+                _get_leaves(result), self.destination_prefix
+            )
+        return result, {}
 
     def _iter_destination_classes(self) -> list[type]:
         out: list[type] = []
+        visited: set[type] = set()
+
+        def visit(candidate: type) -> None:
+            if candidate in visited:
+                return
+            visited.add(candidate)
+            if dataclasses.is_dataclass(candidate):
+                out.append(candidate)
+            for _, child in vars(candidate).items():
+                if isinstance(child, type):
+                    visit(child)
+
         for _, obj in vars(self.model_module).items():
-            if isinstance(obj, type) and dataclasses.is_dataclass(obj):
-                out.append(obj)
+            if isinstance(obj, type):
+                visit(obj)
         return out
 
     def _patch_dataclasses(self) -> None:
         for cls in self._iter_destination_classes():
+            if cls in self._orig_inits:
+                continue
             orig_init_obj = vars(cls).get("__init__")
             if not callable(orig_init_obj):
                 continue
@@ -316,36 +342,58 @@ class TraceContext:
                 __orig: InitCallable = orig_init,
                 **kwargs: t.Any,
             ) -> None:
-                # assign a sibling index for this instance (1-based)
-                name = _xml_class_name(__cls)
-                self._state.push(name)
-                try:
-                    # Call the real __init__ first so attributes exist
-                    __orig(_self, *args, **kwargs)
-                    # Now inspect assigned fields from kwargs by name
-                    for f in dataclasses.fields(__cls):
-                        if f.name in kwargs:
-                            val = kwargs[f.name]
-                            if isinstance(val, Tagged):
-                                _record_scalar_field(self._state, __cls, f.name, val)
-                            elif isinstance(val, (list, tuple)):
-                                _record_list_field(self._state, __cls, f.name, val)
-                            # nested dataclasses will record deeper leaves on their own in their own init
-                finally:
-                    self._state.pop()
+                xml_self_name = _xml_class_name(__cls)
+                direct_leaves: list[LeafRecord] = []
+                kwargs_for_init: dict[str, t.Any] = dict(kwargs)
+
+                for f in dataclasses.fields(__cls):
+                    if f.name not in kwargs_for_init:
+                        continue
+                    raw_value = kwargs_for_init[f.name]
+                    unwrapped, leaves = _unwrap_field_value(__cls, f.name, raw_value)
+                    kwargs_for_init[f.name] = unwrapped
+                    for segments, src_path in leaves:
+                        direct_leaves.append(([xml_self_name] + segments, src_path))
+
+                __orig(_self, *args, **kwargs_for_init)
+
+                all_leaves = list(direct_leaves)
+                for f in dataclasses.fields(__cls):
+                    with contextlib.suppress(Exception):
+                        field_value = getattr(_self, f.name)
+                        if dataclasses.is_dataclass(field_value):
+                            nested_name = _nested_segment_name(
+                                __cls, f.name, field_value
+                            )
+                            for segments, src_path in _get_leaves(field_value):
+                                tail = segments[1:] if segments else []
+                                all_leaves.append(
+                                    ([xml_self_name, nested_name] + tail, src_path)
+                                )
+                        elif isinstance(field_value, (list, tuple)):
+                            for item in field_value:
+                                if dataclasses.is_dataclass(item):
+                                    nested_name = _nested_segment_name(
+                                        __cls, f.name, item
+                                    )
+                                    for segments, src_path in _get_leaves(item):
+                                        tail = segments[1:] if segments else []
+                                        all_leaves.append(
+                                            (
+                                                [xml_self_name, nested_name] + tail,
+                                                src_path,
+                                            )
+                                        )
+
+                setattr(_self, TRACER_LEAVES_ATTR, all_leaves)
 
             type.__setattr__(cls, "__init__", wrapper)
-            self._patched_classes.append(cls)
 
     def _restore_dataclasses(self) -> None:
         with contextlib.suppress(Exception):
             for cls, orig in self._orig_inits.items():
                 type.__setattr__(cls, "__init__", orig)
-
         self._orig_inits.clear()
-        self._patched_classes.clear()
-
-    # ---- patch enum meta (unwrap Tagged keys) ----
 
     def _patch_enum_meta(self) -> None:
         if self._orig_enummeta_getitem is not None:
@@ -358,11 +406,14 @@ class TraceContext:
         )
 
         def patched_getitem(cls: type[enum.Enum], name: t.Any) -> t.Any:
-            if isinstance(name, Tagged):
-                name = name.value
             getter = self._orig_enummeta_getitem
             if getter is None:
                 raise RuntimeError("EnumMeta.__getitem__ patch is not installed")
+
+            if isinstance(name, Tagged):
+                member = getter(cls, name.value)
+                return Tagged(member, name.path)
+
             return getter(cls, name)
 
         type.__setattr__(enum.EnumMeta, "__getitem__", patched_getitem)
@@ -372,18 +423,12 @@ class TraceContext:
             type.__setattr__(enum.EnumMeta, "__getitem__", self._orig_enummeta_getitem)
             self._orig_enummeta_getitem = None
 
-    # ---- lift helper functions ----
-
     def _resolve_lift_target(self, spec: str) -> tuple[types.ModuleType, str] | None:
-        """
-        Resolve 'name' in converter's globals, or 'pkg.mod:func' fully-qualified.
-        Returns (module_object, attribute_name).
-        """
         if ":" in spec:
             mod_name, attr = spec.split(":", 1)
             imported_mod = __import__(mod_name, fromlist=[attr])
             return (imported_mod, attr)
-        # try converter's globals
+
         converter_mod = inspect.getmodule(self.converter)
         if converter_mod and hasattr(converter_mod, spec):
             return (converter_mod, spec)
@@ -400,7 +445,6 @@ class TraceContext:
             def lifted(
                 *args: t.Any, __orig: t.Callable[..., t.Any] = orig, **kwargs: t.Any
             ) -> t.Any:
-                # If any arg is Tagged, unwrap the value(s), remember first path
                 first_tag_path: str | None = None
 
                 def unwrap(x: t.Any) -> t.Any:
@@ -413,12 +457,9 @@ class TraceContext:
                 ua = tuple(unwrap(a) for a in args)
                 uk = {k: unwrap(v) for k, v in kwargs.items()}
                 out = __orig(*ua, **uk)
-                # Re-wrap scalar outputs to keep the path flowing
-                if (
-                    first_tag_path is not None
-                    and not dataclasses.is_dataclass(out)
-                    and not isinstance(out, (list, tuple, dict))
-                ):
+                if first_tag_path is not None:
+                    if isinstance(out, Tagged):
+                        return out
                     return Tagged(out, first_tag_path)
                 return out
 
@@ -429,5 +470,4 @@ class TraceContext:
         with contextlib.suppress(Exception):
             for mod, attr, orig in self._lifted:
                 setattr(mod, attr, orig)
-
         self._lifted.clear()

pathbridge-0.2.0/src/pathbridge/extras/shaper.py

@@ -1,246 +0,0 @@
-from __future__ import annotations
-
-import dataclasses
-import datetime as dt
-import inspect
-import types
-import typing as t
-from decimal import Decimal
-from enum import Enum
-from uuid import UUID
-
-T = t.TypeVar("T")
-
-
-def _is_dataclass_type(tp: t.Any) -> t.TypeGuard[type[t.Any]]:
-    return inspect.isclass(tp) and dataclasses.is_dataclass(tp)
-
-
-def _dataclass_fields(cls: type[t.Any]) -> tuple[dataclasses.Field[t.Any], ...]:
-    return dataclasses.fields(cls)
-
-
-def _is_optional(tp: t.Any) -> tuple[bool, t.Any]:
-    """Return (is_optional, inner_type)."""
-    origin = t.get_origin(tp)
-    if origin in (t.Union, types.UnionType):  # Optional[T] is Union[T, NoneType]
-        args = [a for a in t.get_args(tp) if a is not type(None)]
-        if len(args) == 1:
-            return True, args[0]
-    return False, tp
-
-
-def _is_list(tp: t.Any) -> tuple[bool, t.Any]:
-    origin = t.get_origin(tp)
-    if origin in (list, list):
-        args = t.get_args(tp)
-        return True, (args[0] if args else t.Any)
-    return False, tp
-
-
-def _is_dict(tp: t.Any) -> tuple[bool, t.Any, t.Any]:
-    origin = t.get_origin(tp)
-    if origin in (dict, dict):
-        args = t.get_args(tp)
-        key_t = args[0] if args else t.Any
-        val_t = args[1] if len(args) > 1 else t.Any
-        return True, key_t, val_t
-    return False, tp, tp
-
-
-def _safe_first_enum(enum_cls: type[Enum]) -> Enum:
-    try:
-        return next(iter(enum_cls))
-    except StopIteration:
-        raise ValueError(f"Enum {enum_cls!r} has no members") from None
-
-
-def _default_for_type(tp: t.Any) -> t.Any:
-    """Produce a non-empty, truthy default for a scalar-ish type."""
-    if tp in (str, str, t.Any):
-        return "x"
-    if tp in (int,):
-        return 1
-    if tp in (float,):
-        return 1.0
-    if tp is Decimal:
-        return Decimal("1")
-    if tp is bool:
-        return True
-    if tp is dt.date:
-        return dt.date.today()
-    if tp is dt.datetime:
-        return dt.datetime.now()
-    if tp is UUID:
-        return UUID(int=1)
-    return "x"  # generic truthy fallback
-
-
-def _apply_overrides(obj: t.Any, overrides: dict[str, t.Any]) -> t.Any:
-    """
-    Apply dotted-path overrides like:
-      "foo.bar[2].baz": 42
-    Works with dataclasses, lists, and dicts.
-    """
-    for path, value in overrides.items():
-        parts = [p for p in path.split(".") if p]
-        target = obj
-        for i, token in enumerate(parts):
-            # handle [idx] suffix
-            name, idx = token, None
-            if "[" in token and token.endswith("]"):
-                name, idx = (
-                    token[: token.index("[")],
-                    int(token[token.index("[") + 1 : -1]),
-                )
-
-            if i == len(parts) - 1:
-                # set leaf
-                if idx is None:
-                    if dataclasses.is_dataclass(target):
-                        setattr(target, name, value)
-                    elif isinstance(target, dict):
-                        target[name] = value
-                    else:
-                        setattr(target, name, value)
-                else:
-                    seq = getattr(target, name)
-                    seq[idx] = value
-                break
-
-            # descend
-            if dataclasses.is_dataclass(target):
-                target = getattr(target, name)
-            elif isinstance(target, dict):
-                target = target[name]
-            else:
-                target = getattr(target, name)
-
-            if idx is not None:
-                target = target[idx]
-    return obj
-
-
-def _shape_dataclass(
-    cls: type[T],
-    *,
-    list_len: int,
-    overrides: dict[str, t.Any] | None,
-    seen: set[type],
-) -> T:
-    if cls in seen:
-        # stop infinite recursion; build minimal
-        minimal_kwargs: dict[str, t.Any] = {}
-        for f in _dataclass_fields(cls):
-            minimal_kwargs[f.name] = None
-        return cls(**minimal_kwargs)
-    seen.add(cls)
-
-    kwargs: dict[str, t.Any] = {}
-    for f in _dataclass_fields(cls):
-        tp = f.type
-        is_opt, inner = _is_optional(tp)
-        if is_opt:
-            tp = inner
-
-        is_list, elem_t = _is_list(tp)
-        if is_list:
-            elems: list[t.Any] = []
-            for _ in range(list_len):
-                if _is_dataclass_type(elem_t):
-                    elems.append(
-                        _shape_dataclass(
-                            elem_t, list_len=list_len, overrides=None, seen=seen
-                        )
-                    )
-                else:
-                    # nested optionals, enums, scalars
-                    opt2, inner2 = _is_optional(elem_t)
-                    if opt2:
-                        elem_t = inner2
-                    if inspect.isclass(elem_t) and issubclass(elem_t, Enum):
-                        elems.append(_safe_first_enum(elem_t))
-                    else:
-                        elems.append(_default_for_type(elem_t))
-            kwargs[f.name] = elems
-            continue
-
-        is_dict, key_t, val_t = _is_dict(tp)
-        if is_dict:
-            # make a tiny dict with one truthy item
-            k = "k" if key_t is str else 1
-            if _is_dataclass_type(val_t):
-                v = _shape_dataclass(
-                    val_t, list_len=list_len, overrides=None, seen=seen
-                )
-            else:
-                v = _default_for_type(val_t)
-            kwargs[f.name] = {k: v}
-            continue
-
-        # nested dataclass
-        if _is_dataclass_type(tp):
-            kwargs[f.name] = _shape_dataclass(
-                tp, list_len=list_len, overrides=None, seen=seen
-            )
-            continue
-
-        # enums
-        if inspect.isclass(tp) and issubclass(tp, Enum):
-            kwargs[f.name] = _safe_first_enum(tp)
-            continue
-
-        # scalar fallback
-        kwargs[f.name] = _default_for_type(tp)
-
-    inst = cls(**kwargs)
-    if overrides:
-        _apply_overrides(inst, overrides)
-    seen.remove(cls)
-    return inst
-
-
-def make_shape(
-    spec: type[T] | T | t.Callable[[], T],
-    *,
-    list_len: int = 1,
-    overrides: dict[str, t.Any] | None = None,
-) -> T:
-    """
-    Construct a 'truthy' instance for the given facade class/instance/factory.
-
-    - spec: dataclass class, an instance (will be cloned shallowly), or a zero-arg factory
-    - list_len: default length for list fields
-    - overrides: dotted-path -> value to force (supports [index])
-
-    Heuristics:
-      - dataclasses: recursively instantiate with non-empty defaults
-      - Optional[T]: pick T with a non-empty value
-      - enums: pick first member
-      - str: "x"; int: 1; Decimal: 1; bool: True; date: today
-      - lists: [truthy(T) for _ in range(list_len)]
-    """
-    if inspect.isclass(spec):
-        if dataclasses.is_dataclass(spec):
-            base = _shape_dataclass(
-                t.cast(type[T], spec),
-                list_len=list_len,
-                overrides=overrides,
-                seen=set(),
-            )
-        else:
-            raise TypeError(
-                "make_shape expects a dataclass class/instance or a zero-arg factory"
-            )
-    elif dataclasses.is_dataclass(spec):
-        # already an instance: (re)apply overrides and return
-        base = t.cast(T, spec)
-        if overrides:
-            _apply_overrides(base, overrides)
-    elif callable(spec):
-        base = spec()
-    else:
-        raise TypeError(
-            "make_shape expects a dataclass class/instance or a zero-arg factory"
-        )
-    return base