smartdict 0.4.0__py3-none-any.whl

smartdict/__init__.py

@@ -0,0 +1,36 @@
+from smartdict.resolver import RefStringStatus, RefStringStatusWithValue, ComponentWithValue
+from smartdict.smartdict import (
+    SmartDict,
+    CircularReferenceError,
+    ReferenceNotFoundError,
+    UnresolvedReference,
+)
+from smartdict.path import Path
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "parse",
+    "partial_parse",
+    "iterative_parse",
+    "RefStringStatus",
+    "RefStringStatusWithValue",
+    "ComponentWithValue",
+    "SmartDict",
+    "CircularReferenceError",
+    "ReferenceNotFoundError",
+    "UnresolvedReference",
+    "Path"
+]
+
+
+def parse(obj):
+    return SmartDict(data=obj).parse()
+
+
+def partial_parse(obj):
+    return SmartDict(data=obj, partial=True).parse()
+
+
+def iterative_parse(obj, iterations=1):
+    return SmartDict(data=obj, iterations=iterations, partial=True).parse()

smartdict/function.py

@@ -0,0 +1,50 @@
+class Part:
+    def __init__(self, part: str, full: bool = False, partial: bool = False):
+        self.part = part
+        self.full = full
+        self.partial = partial
+
+    def __call__(self):
+        if self.full:
+            return '${' + self.part + '}$'
+        if self.partial:
+            return '${' + self.part + '}'
+        return self.part
+
+
+def parse_ref_string(s: str) -> list[Part]:
+    parts = []
+    i = 0
+    n = len(s)
+
+    while i < n:
+        if s[i:i + 2] == '${':  # 进入引用
+            depth = 1
+            j = i + 2
+            while j < n and depth > 0:
+                if s[j:j + 2] == '${':
+                    depth += 1
+                    j += 2
+                elif s[j] == '}':
+                    depth -= 1
+                    j += 1
+                else:
+                    j += 1
+            if depth != 0:
+                raise ValueError(f"Unmatched braces in: {s}")
+            expr = s[i + 2:j - 1]  # 提取 ${ ... }
+
+            # full 的严格条件：整个字符串是 ${...}$
+            if i == 0 and j == n - 1 and s.endswith('$'):
+                parts.append(Part(expr, full=True))
+                return parts  # 整个字符串就是 full，直接返回
+            else:
+                parts.append(Part(expr, partial=True))
+            i = j
+        else:
+            # 普通文本
+            start = i
+            while i < n and s[i:i + 2] != '${':
+                i += 1
+            parts.append(Part(s[start:i]))
+    return parts

smartdict/path.py

@@ -0,0 +1,20 @@
+class Path:
+    def __init__(self, path=None):
+        self._path = path or []
+
+    def __truediv__(self, other):
+        if isinstance(other, str):
+            return Path(self._path.copy() + [other])
+        if isinstance(other, Path):
+            return Path(self._path.copy() + other._path.copy())
+        raise TypeError(f'Path `/` operation get unexpected type {type(other)}')
+
+    def __call__(self):
+        return '→'.join(self._path)
+
+    def __len__(self):
+        return len(self._path)
+
+    def __str__(self):
+        path = list(map(lambda x: f'{x}', self._path))
+        return ' → '.join(path)

smartdict/resolver.py

@@ -0,0 +1,92 @@
+from typing import Any, Dict, Union
+
+
+class RefStringStatus:
+    RESOLVING = object()
+    UNRESOLVED = object()
+    RESOLVED = object()
+    NOTFOUND = object()
+
+    UNSET_VALUE = object()
+
+    def __init__(self, ref_string):
+        self.ref_string = ref_string
+
+        self.status = self.RESOLVING
+        self.value = self.UNSET_VALUE
+
+    @property
+    def is_resolved(self):
+        return self.status == self.RESOLVED
+
+    @property
+    def is_unresolved(self):
+        return self.status == self.UNRESOLVED
+
+    @property
+    def is_resolving(self):
+        return self.status == self.RESOLVING
+
+    def resolve(self, value):
+        self.status = self.RESOLVED
+        self.value = value
+        return self
+
+    def unresolve(self):
+        self.status = self.UNRESOLVED
+        return self
+
+    @property
+    def has_value(self):
+        return self.value != self.UNSET_VALUE
+
+    def __str__(self):
+        value = self.value if self.has_value else '<UNSET>'
+        return f'{self.ref_string} → {value}'
+
+    def __repr__(self):
+        return str(self)
+
+
+class RefStringStatusWithValue:
+    def __init__(self, status: RefStringStatus, value: Any = RefStringStatus.UNSET_VALUE):
+        self.status = status
+        self.value = value
+
+        if status.is_resolved:
+            self.value = status.value
+
+    @property
+    def is_unset(self):
+        return self.value == RefStringStatus.UNSET_VALUE
+
+
+class ComponentWithValue:
+    def __init__(self, path):
+        super().__init__()
+        self.path = str(path)
+        self.unresolved = {}  # type: Dict[Any, Union[RefStringStatus, ComponentWithValue]]
+        self.final = None
+
+    def push(self, ref_value: RefStringStatusWithValue):
+        if ref_value.is_unset:
+            self.unresolved[ref_value.status.ref_string] = ref_value.status
+        return self
+
+    def list_push(self, index, component_value: 'ComponentWithValue'):
+        if component_value.has_unresolved:
+            self.unresolved[str(index)] = component_value
+        return self
+
+    def dict_push(self, key, component_value: 'ComponentWithValue'):
+        if component_value.has_unresolved:
+            self.unresolved[key] = component_value
+        return self
+
+    def finalize(self, obj):
+        self.final = obj
+        return self
+
+    @property
+    def has_unresolved(self):
+        return len(self.unresolved) > 0

smartdict/roba.py

@@ -0,0 +1,50 @@
+import re
+
+from oba.oba import raw, NotFound, iterable, Obj
+
+
+pattern = re.compile(r"\$\{[^}]+}|[^.]+")
+
+def re_split(s: str):
+    tokens = pattern.findall(s)
+    if len(tokens) > 1:
+        tokens = [tokens[0], '.'.join(tokens[1:])]
+    return tokens
+
+
+class Roba(Obj):
+    def __init__(self, object_=None, path=None):
+        super().__init__(object_, path)
+
+    def __getitem__(self, key):
+        if isinstance(key, str):
+            key = re_split(key)
+
+        index = key[0] if isinstance(key, list) else key
+
+        # noinspection PyBroadException
+        try:
+            value = self.__obj__.__getitem__(index)
+        except Exception:
+            return NotFound(path=self.__path__ / index)
+        if iterable(value):
+            value = Roba(value, path=self.__path__ / str(key))
+
+        if isinstance(key, list) and len(key) > 1:
+            value = value[key[1]]
+        return value
+
+    def __setitem__(self, key: str, value):
+        key = re_split(key)
+        print(key,)
+
+        if len(key) == 1:
+            obj = raw(self)
+            obj[key[0]] = value
+        else:
+            print('here')
+            print(type(self[key[0]]))
+            self[key[0]][key[1]] = value
+
+    def __str__(self):
+        return 'Soba()'

smartdict/smartdict.py

@@ -0,0 +1,336 @@
+import warnings
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Hashable
+
+from smartdict import function
+from smartdict.path import Path
+from smartdict.resolver import RefStringStatus, ComponentWithValue, RefStringStatusWithValue
+from smartdict.roba import Roba
+
+
+@dataclass(frozen=True)
+class UnresolvedReference:
+    path: str
+    reference: str
+
+
+class CircularReferenceError(ReferenceError):
+    """Raised when a reference dependency chain loops back to itself."""
+
+    def __init__(self, ref_string: str):
+        self.ref_string = ref_string
+        super().__init__(f'Circular reference detected: {ref_string}')
+
+
+class ReferenceNotFoundError(KeyError):
+    """Raised when strict parsing encounters unresolved references."""
+
+    def __init__(self, unresolved: list[UnresolvedReference]):
+        self.unresolved = tuple(unresolved)
+        details = ', '.join(
+            f'{item.path or "<root>"} -> {item.reference}' for item in self.unresolved
+        )
+        super().__init__(f'Unresolved references: {details}')
+
+
+# _FULL_REF_PATTERN = re.compile(r"^\$\{([^}]+)}\$$")
+# _PARTIAL_REF_PATTERN = re.compile(r"\$\{([^}]+)}")
+
+
+class SmartDict:
+    def __init__(self, data: Any, partial: bool = False, iterations=1):
+        if iterations <= 0:
+            raise ValueError('`iterations` must be greater than 0')
+
+        self._src = data
+        self._cache = {}  # type: Dict[str, RefStringStatus]
+        self._partial = partial
+        self._iterations = iterations
+
+        if self._iterations > 1 and not self._partial:
+            self._partial = True
+            warnings.warn('`partial` will be set to True when `iteration` > 1')
+
+    def combine_and_parse(self, cache: dict, return_cv=False):
+        roba = Roba(self._src)
+        for key, value in cache.items():
+            roba[key] = value
+        self._src = roba()
+
+        component_value = self.deep_resolve(self._src)
+        src = component_value.final
+
+        self._analyse(component_value)
+
+        if return_cv:
+            return component_value
+
+        return src
+
+    def parse(self, return_cv=False) -> Any:
+        iter_src = self._src
+        component_value = None  # type: Optional[ComponentWithValue]
+        for _ in range(self._iterations):
+            self._cache.clear()
+            component_value = self.deep_resolve(iter_src)
+            iter_src = component_value.final
+
+        if component_value is None:
+            raise RuntimeError('source is not parsed yet')
+
+        self._analyse(component_value)
+
+        if return_cv:
+            return component_value
+
+        return iter_src
+
+    def _collect_unresolved(self, component_value: ComponentWithValue) -> list[UnresolvedReference]:
+        unresolved = []
+        for value in component_value.unresolved.values():
+            if isinstance(value, ComponentWithValue):
+                unresolved.extend(self._collect_unresolved(value))
+            elif isinstance(value, RefStringStatus):
+                unresolved.append(
+                    UnresolvedReference(
+                        path=component_value.path,
+                        reference=value.ref_string,
+                    )
+                )
+            else:
+                raise RuntimeError(f'unexpected type {type(value)}')
+        return unresolved
+
+    def _analyse(self, component_value: ComponentWithValue):
+        if self._partial or not component_value.has_unresolved:
+            return
+
+        raise ReferenceNotFoundError(self._collect_unresolved(component_value))
+
+    @staticmethod
+    def is_string(obj: Any) -> bool:
+        return isinstance(obj, str)
+
+    @staticmethod
+    def is_dict(obj: Any) -> bool:
+        return isinstance(obj, dict)
+
+    @staticmethod
+    def is_list(obj: Any) -> bool:
+        return isinstance(obj, list)
+
+    @classmethod
+    def is_tuple(cls: Any, obj: Any) -> bool:
+        return isinstance(obj, tuple)
+
+    def deep_resolve(self, obj: Any, path: Path = None) -> ComponentWithValue:
+        path = path or Path()
+
+        if self.is_string(obj):
+            return self._resolve_string(obj, path=path)
+
+        final_component_value = ComponentWithValue(path)
+
+        if self.is_list(obj) or self.is_tuple(obj):
+            new_list = []
+            for i, item in enumerate(obj):
+                component_value = self.deep_resolve(item, path=path / str(i))
+                new_list.append(component_value.final)
+                final_component_value.list_push(str(i), component_value)
+            if self.is_tuple(obj):
+                new_list = tuple(new_list)
+            return final_component_value.finalize(new_list)
+
+        if self.is_dict(obj):
+            new_dict = {}
+            for key, value in obj.items():
+                key_path = path / f'<k>' / key
+                key_component_value = self.deep_resolve(key, path=key_path)
+                final_component_value.dict_push(f'<k> / {key}', key_component_value)
+                if not isinstance(key_component_value.final, Hashable):
+                    raise TypeError(f'Key object is not hashable: {key_component_value.final}')
+                new_key = key_component_value.final
+
+                if new_key in new_dict:
+                    raise KeyError(f'Duplicate key: {new_key}')
+
+                value_component_value = self.deep_resolve(value, path=path / str(new_key))
+                final_component_value.dict_push(new_key, value_component_value)
+                new_dict[new_key] = value_component_value.final
+            return final_component_value.finalize(new_dict)
+
+        return final_component_value.finalize(obj)
+
+    @staticmethod
+    def _parse_default_value(value: Any) -> Any:
+        """
+        Automatically parses the type of default values:
+          - "true" / "false" / "null" (case-insensitive)
+          - Integers
+          - Floats
+          - Otherwise, keeps the string as-is
+        """
+        if isinstance(value, str):
+            lower_val = value.lower()
+            if lower_val == "true":
+                return True
+            elif lower_val == "false":
+                return False
+            elif lower_val == "null":
+                return None
+            else:
+                # Attempt to parse as int
+                try:
+                    return int(value)
+                except ValueError:
+                    pass
+                # Attempt to parse as float
+                try:
+                    return float(value)
+                except ValueError:
+                    pass
+                # Keep as string
+                return value
+        else:
+            # Non-string types remain unchanged
+            return value
+
+    @staticmethod
+    def _get_value(obj: Any, key):
+        try:
+            return obj[key]
+        except Exception:
+            pass
+
+        try:
+            return getattr(obj, key)
+        except Exception:
+            pass
+
+        try:
+            return obj[int(key)]
+        except Exception:
+            pass
+
+        return RefStringStatus.NOTFOUND
+
+    def _resolve_path_component(self, value: Any, path: Path, is_leaf: bool):
+        if is_leaf:
+            return self.deep_resolve(value, path).final
+
+        # Only resolve string aliases for intermediate nodes so we can keep
+        # walking the requested path without eagerly resolving sibling fields.
+        while self.is_string(value):
+            resolved = self.deep_resolve(value, path).final
+            if resolved == value:
+                break
+            value = resolved
+
+        return value
+
+    def _resolve_ref_string(self, ref_string: str, path: Path) -> RefStringStatusWithValue:
+        if ':' in ref_string:
+            ref_string, default_str = ref_string.split(':', 1)
+            default_value = self._parse_default_value(default_str)
+        else:
+            default_value = RefStringStatus.UNSET_VALUE
+
+        if ref_string in self._cache:
+            if self._cache[ref_string].is_resolving:
+                raise CircularReferenceError(ref_string)
+            return RefStringStatusWithValue(self._cache[ref_string], default_value)
+
+        self._cache[ref_string] = RefStringStatus(ref_string)
+        subkeys = ref_string.split(".") if ref_string else []
+        current_value = self._src
+        current_path = path
+        last_index = len(subkeys) - 1
+        for index, key in enumerate(subkeys):
+            current_path = current_path / key
+            current_value = self._get_value(current_value, key)
+            if current_value is RefStringStatus.NOTFOUND:
+                break
+            current_value = self._resolve_path_component(
+                current_value,
+                current_path,
+                is_leaf=index == last_index,
+            )
+
+        if current_value is RefStringStatus.NOTFOUND:
+            self._cache[ref_string].unresolve()
+        else:
+            self._cache[ref_string].resolve(current_value)
+        return RefStringStatusWithValue(self._cache[ref_string], default_value)
+
+    def _resolve_string(self, obj: str, path: Path) -> ComponentWithValue:
+        component_value = ComponentWithValue(path)
+
+        parts = function.parse_ref_string(obj)
+        if len(parts) == 1 and parts[0].full:
+            ref_string = self._resolve_string(parts[0].part, path).final
+            ref_value = self._resolve_ref_string(ref_string, path=path / '$')
+            return component_value.push(ref_value).finalize(obj if ref_value.is_unset else ref_value.value)
+
+        # m_full = _FULL_REF_PATTERN.match(obj)
+        #
+        # if m_full:
+        #     ref_value = self._resolve_ref_string(m_full.group(1), path=path / '$')
+        #     return component_value.push(ref_value).finalize(obj if ref_value.is_unset else ref_value.value)
+
+        result_parts = []
+
+        for p in parts:
+            if not p.partial:
+                result_parts.append(p.part)
+                continue
+            ref_string = self._resolve_string(p.part, path).final
+            ref_value = self._resolve_ref_string(ref_string, path=path / '$')
+            current = '${' + ref_string + '}' if ref_value.is_unset else ref_value.value
+            component_value.push(ref_value)
+
+            result_parts.append(str(current))
+
+        return component_value.finalize(''.join(result_parts))
+
+
+        #
+        # matches = list(_PARTIAL_REF_PATTERN.finditer(obj))
+        # if not matches:
+        #     return component_value.finalize(obj)
+        #
+        # result_parts = []
+        # last_end = 0
+        # for m in matches:
+        #     start_idx = m.start()
+        #     end_idx = m.end()
+        #     # Add the original text before this reference
+        #     result_parts.append(obj[last_end:start_idx])
+        #
+        #     ref_value = self._resolve_ref_string(m.group(1), path=path / '$')
+        #     current = m.group(0) if ref_value.is_unset else ref_value.value
+        #     component_value.push(ref_value)
+        #
+        #     result_parts.append(str(current))
+        #
+        #     last_end = end_idx
+        # # Add the remaining text after the last reference
+        # result_parts.append(obj[last_end:])
+        #
+        # return component_value.finalize("".join(result_parts))
+
+    @property
+    def cache(self):
+        return self._cache
+
+
+if __name__ == '__main__':
+    data_ = {
+        'a': {
+            'z': 1,
+            'b${a.y}': '${a.b}$',
+            'c': '${a.b1}bad',
+            'b': 33,
+        }
+    }
+    data_ = SmartDict(data_).parse()
+    print(data_)

smartdict-0.4.0.dist-info/METADATA

@@ -0,0 +1,433 @@
+Metadata-Version: 2.4
+Name: smartdict
+Version: 0.4.0
+Summary: A reference resolver for nested dictionaries that supports default values, partial references, and circular dependency detection.
+Author-email: Jyonn Liu <i@6-79.cn>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Jyonn/smartdict
+Keywords: dict,reference
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: oba>=0.3.0
+
+# SmartDict
+
+`smartdict` is a small Python library for resolving references inside nested data structures.
+It is especially useful for configuration dictionaries where one field needs to reuse another.
+
+SmartDict walks through built-in `dict`, `list`, and `tuple` containers, finds reference
+expressions inside strings, and replaces them with resolved values.
+
+## Features
+
+- Inline string interpolation with `${path.to.value}`
+- Full-value replacement with `${path.to.value}$`
+- Nested reference strings such as `${${keys.${env}}}`
+- Default values such as `${missing:42}` or `${missing:fallback}`
+- Dictionary key generation from references
+- List and tuple index lookup through dotted paths
+- Circular reference detection
+- Strict mode, partial mode, and iterative parsing mode
+
+## Installation
+
+```bash
+pip install smartdict
+```
+
+## Quick Start
+
+```python
+import smartdict
+
+data = {
+    "dataset": "spotify",
+    "load": {
+        "base_path": "~/data/${dataset}",
+        "train_path": "${load.base_path}/train",
+        "dev_path": "${load.base_path}/dev",
+        "test_path": "${load.base_path}/test",
+    },
+    "network": {
+        "num_hidden_layers": 3,
+        "num_attention_heads": 8,
+    },
+    "store": "checkpoints/${dataset}/${network.num_hidden_layers}L${network.num_attention_heads}H/",
+}
+
+parsed = smartdict.parse(data)
+
+print(parsed["load"]["base_path"])
+# ~/data/spotify
+
+print(parsed["load"]["dev_path"])
+# ~/data/spotify/dev
+
+print(parsed["store"])
+# checkpoints/spotify/3L8H/
+```
+
+## Reference Syntax
+
+### 1. Inline references
+
+Use `${...}` when the reference is part of a larger string.
+
+```python
+import smartdict
+
+parsed = smartdict.parse({
+    "name": "smartdict",
+    "message": "hello-${name}",
+})
+
+print(parsed["message"])
+# hello-smartdict
+```
+
+### 2. Full-match references
+
+Use `${...}$` when the whole value should become the referenced object instead of a string.
+
+```python
+import smartdict
+
+parsed = smartdict.parse({
+    "config": {
+        "debug": True,
+        "retries": 3,
+    },
+    "selected": "${config}$",
+})
+
+print(parsed["selected"])
+# {'debug': True, 'retries': 3}
+```
+
+This is useful when the target is a `dict`, `list`, `tuple`, number, boolean, or any other
+non-string value.
+
+### 3. Nested reference strings
+
+Reference expressions can themselves contain reference expressions.
+
+```python
+import smartdict
+
+parsed = smartdict.parse({
+    "env": "prod",
+    "keys": {"prod": "url"},
+    "url": "https://example.com",
+    "result": "${${keys.${env}}}",
+})
+
+print(parsed["result"])
+# https://example.com
+```
+
+### 4. Default values
+
+If a path cannot be found, you can provide a default value with `:`.
+
+```python
+import smartdict
+
+parsed = smartdict.parse({
+    "int_value": "${missing:42}$",
+    "bool_value": "${missing:true}$",
+    "null_value": "${missing:null}$",
+    "text_value": "${missing:fallback}$",
+})
+
+print(parsed)
+# {
+#   'int_value': 42,
+#   'bool_value': True,
+#   'null_value': None,
+#   'text_value': 'fallback'
+# }
+```
+
+Default values are automatically interpreted as:
+
+- `true` / `false` -> `bool`
+- `null` -> `None`
+- integers -> `int`
+- floats -> `float`
+- anything else -> `str`
+
+### 5. List and tuple indices
+
+Dotted paths can also index built-in sequences.
+
+```python
+import smartdict
+
+parsed = smartdict.parse({
+    "items": ["a", "b"],
+    "pair": ("x", "y"),
+    "pick_list": "${items.1}",
+    "pick_tuple": "${pair.0}",
+})
+
+print(parsed["pick_list"])
+# b
+
+print(parsed["pick_tuple"])
+# x
+```
+
+### 6. Dictionary keys can be generated
+
+References are resolved in both keys and values.
+
+```python
+import smartdict
+
+parsed = smartdict.parse({
+    "name": "k",
+    "${name}": 1,
+})
+
+print(parsed)
+# {'name': 'k', 'k': 1}
+```
+
+### 7. Referencing custom objects
+
+SmartDict resolves path components in this order:
+
+1. `obj[key]`
+2. `getattr(obj, key)`
+3. `obj[int(key)]`
+
+That means you can expose custom lookup behavior through objects used inside your data.
+
+```python
+import random
+import string
+
+import smartdict
+
+
+class Rand(dict):
+    chars = string.ascii_letters + string.digits
+
+    def __getitem__(self, item):
+        return "".join(random.choice(self.chars) for _ in range(int(item)))
+
+
+parsed = smartdict.parse({
+    "utils": {
+        "rand": Rand(),
+    },
+    "filename": "${utils.rand.4}",
+})
+
+print(parsed["filename"])
+# for example: aZ19
+```
+
+## Parse Modes
+
+### `smartdict.parse(obj)`
+
+Strict mode.
+
+- Resolves all references
+- Raises an error if any reference cannot be resolved
+- Detects circular references
+
+```python
+import smartdict
+
+parsed = smartdict.parse({
+    "a": "x",
+    "b": "${a}/y",
+})
+
+print(parsed)
+# {'a': 'x', 'b': 'x/y'}
+```
+
+### `smartdict.partial_parse(obj)`
+
+Best-effort mode.
+
+- Resolves what it can
+- Does not raise for missing references
+- Leaves unresolved results in their current best-effort form
+
+```python
+import smartdict
+
+parsed = smartdict.partial_parse({
+    "a": "${missing}",
+    "b": "pre-${missing}-post",
+    "c": "${missing}$",
+})
+
+print(parsed)
+# {'a': '${missing}', 'b': 'pre-${missing}-post', 'c': '${missing}$'}
+```
+
+### `smartdict.iterative_parse(obj, iterations=1)`
+
+Repeated best-effort parsing.
+
+This is useful when one pass unlocks another pass.
+
+```python
+import smartdict
+
+parsed = smartdict.iterative_parse({
+    "a": "${b}",
+    "b": "${c}",
+    "c": "ok",
+}, iterations=2)
+
+print(parsed)
+# {'a': 'ok', 'b': 'ok', 'c': 'ok'}
+```
+
+## Errors
+
+### `ReferenceNotFoundError`
+
+Raised by `smartdict.parse()` when a reference cannot be resolved.
+
+```python
+import smartdict
+from smartdict.smartdict import ReferenceNotFoundError
+
+try:
+    smartdict.parse({
+        "a": "${missing}",
+    })
+except ReferenceNotFoundError as exc:
+    print(type(exc).__name__, exc)
+```
+
+Nested missing references are also detected:
+
+```python
+import smartdict
+
+smartdict.parse({
+    "app": {
+        "profile": "prod",
+    },
+    "services": {
+        "prod": {
+            "url": "${config.endpoints.api}",
+        },
+    },
+    "result": "${services.${app.profile}.url}",
+})
+```
+
+### `CircularReferenceError`
+
+Raised when references depend on each other in a cycle.
+
+```python
+import smartdict
+from smartdict.smartdict import CircularReferenceError
+
+try:
+    smartdict.parse({
+        "a": "${b}$",
+        "b": "${a}$",
+    })
+except CircularReferenceError as exc:
+    print(type(exc).__name__, exc)
+```
+
+Cycles can also appear across nested dictionaries:
+
+```python
+import smartdict
+
+smartdict.parse({
+    "app": {
+        "profile": "${services.primary.profile}$",
+    },
+    "services": {
+        "primary": {
+            "profile": "${app.profile}$",
+        },
+    },
+})
+```
+
+### `KeyError`
+
+Raised when two dictionary keys resolve to the same final key.
+
+```python
+import smartdict
+
+smartdict.parse({
+    "aliases": {
+        "primary": "stable",
+    },
+    "${aliases.primary}": 1,
+    "stable": 2,
+})
+```
+
+## Public API
+
+The main public entry points are:
+
+```python
+import smartdict
+
+smartdict.parse(obj)
+smartdict.partial_parse(obj)
+smartdict.iterative_parse(obj, iterations=2)
+```
+
+The package also exports:
+
+- `SmartDict`
+- `Path`
+- `CircularReferenceError`
+- `ReferenceNotFoundError`
+- `UnresolvedReference`
+- `RefStringStatus`
+- `RefStringStatusWithValue`
+- `ComponentWithValue`
+
+## Development
+
+Run the test suite with:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Build distributions with:
+
+```bash
+python -m build
+```
+
+## Notes and Current Behavior
+
+- SmartDict recursively parses built-in `dict`, `list`, `tuple`, and `str` values.
+- Intermediate path components can be aliases, including full-match references such as `${config}$`.
+- In strict mode, unresolved references raise `ReferenceNotFoundError`.
+- `ReferenceNotFoundError.unresolved` contains structured unresolved entries with `path` and `reference`.
+- `iterations` must be greater than `0`.
+- If resolved dictionary keys collide, SmartDict raises `KeyError`.
+
+## License
+
+MIT

smartdict-0.4.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+smartdict/__init__.py,sha256=RkVhybvpYdHtzrfNCTdEKUg0Uh9v1-b7FQ7q4JLBTHw,802
+smartdict/function.py,sha256=EBvKwwgc9idM-rQG1eW0Gg5KgMNLeopIGBasAj353II,1501
+smartdict/path.py,sha256=sLyzDAFwVhd8Vqxb8fWPG4rvO2frVFtk8w35-6pvx0o,614
+smartdict/resolver.py,sha256=pfBUqBQUwfx7WTrsurUYC3LCwPxDMnY2A2CuyCVzCNs,2370
+smartdict/roba.py,sha256=byTR5snU7hxDnDDGu6m1SML8ISWKIUJSfTY34eZTNDI,1249
+smartdict/smartdict.py,sha256=ru2k52BCLfTvsnOrLXdpqpT2kF-WcEupOdTRlmPMxL0,11513
+smartdict-0.4.0.dist-info/METADATA,sha256=_9QYF9JeMNbMgCMZlamtr-4Mx8UTSi_b0JAMeKORL1g,8611
+smartdict-0.4.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+smartdict-0.4.0.dist-info/top_level.txt,sha256=XeeTTHZjjhU3dIyVO2syS5Ge4zo8gadnrKu2AHy5gc0,10
+smartdict-0.4.0.dist-info/RECORD,,

smartdict-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

smartdict-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+smartdict