Class _ConfigProxy

monai/bundle/config_parser.py:62–234

Proxy that enables dot-notation and bracket-notation access to nested config structures. When :meth:`ConfigParser.__getattr__` resolves to a ``dict`` or ``list``, the result is wrapped in this proxy so that further attribute and index access chains through the config hierarchy usin

class _ConfigProxy:
    """
    Proxy that enables dot-notation and bracket-notation access to nested config structures.

    When :meth:`ConfigParser.__getattr__` resolves to a ``dict`` or ``list``, the result is
    wrapped in this proxy so that further attribute and index access chains through the
    config hierarchy using :meth:`ConfigParser.get_parsed_content`. For example::

        parser.training.trainer.max_epochs
        # equivalent to
        parser.get_parsed_content("training::trainer::max_epochs")

        parser.transforms[0].keys                 # list indexing chains too
        parser.A.B["C"] = 99                      # writes update the config source
        del parser.A.B["C"]                       # deletes update the config source

    Type caveat:
        Accessing a ``dict``/``list`` member through a :class:`ConfigParser` now returns a
        ``_ConfigProxy``, not the raw container, so ``type(parser.A)`` is ``_ConfigProxy``
        and ``isinstance(parser.A, dict)`` is ``False``. Code that needs the real container
        should use ``parser.A._raw`` (read-only view) or ``parser.get_parsed_content("A")``.

    Precedence and fallback:
        Config keys take precedence over ``dict``/``list`` attributes and methods. If a
        config key is not found, the proxy falls back to the underlying ``dict``/``list``
        so that container methods (``.keys()``, ``.items()`` ...) and native indexing
        semantics (``IndexError``, negative indices, dict ``KeyError``) still work. A
        config key that collides with a container method name (e.g. ``"keys"``) shadows
        that method on attribute access; access it via bracket notation,
        :meth:`ConfigParser.get_parsed_content`, or ``._raw``.

    Writes:
        ``__setitem__``/``__setattr__``/``__delitem__``/``__delattr__`` write through to
        the config *source* (via :class:`ConfigParser`) and reset the reference resolver,
        so the change is visible from both ``parser.<id>`` and
        ``parser.get_parsed_content("<id>")``.
    """

    _INTERNAL = ("_parser", "_id", "_value")

    def __init__(self, parser: ConfigParser, id: str, value: Any):
        """
        Args:
            parser: the owning :class:`ConfigParser`.
            id: the ``::``-separated id this proxy represents.
            value: the parsed ``dict``/``list`` content this proxy wraps.
        """
        self._parser = parser
        self._id = id
        self._value = value

    def _child_id(self, key: str | int) -> str:
        return f"{self._id}{ID_SEP_KEY}{key}"

    def _backing_id(self) -> str:
        """Return the real config id this proxy writes to, resolving all ``$@ref`` hops transitively."""
        current = self._id
        seen: set[str] = set()