liblaf.pretty ¶

def dump(self) -> PrettyOptions:
    """Materialize the current configuration as [`PrettyOptions`][liblaf.pretty.PrettyOptions].

    The returned object is a snapshot of the current environment-backed
    values, with `indent` normalized to [`Text`][rich.text.Text].
    """
    return PrettyOptions(**self.to_dict())

def load_env(self) -> None:
    """Refresh every field from its configured environment variable."""
    for name in self._fields:
        var: Var[Any] = self._get_field(name)
        var.load_env()
    for name in self._groups:
        group: BaseConfig = self._get_group(name)
        group.load_env()

@contextlib.contextmanager
def override(
    self, changes: Mapping[str, Any] | None = None, /, **kwargs: Any
) -> Generator[None]:
    """Temporarily override one or more values within a context manager.

    Args:
        changes: Optional mapping of names to temporary values.
        **kwargs: Additional name-to-value overrides.

    Yields:
        `None` while the overrides are active.
    """
    if changes is not None:
        kwargs.update(changes)
    with contextlib.ExitStack() as stack:
        for name, value in kwargs.items():
            var: BaseConfig | Var[Any] = self._get_field_or_group(name)
            stack.enter_context(var.override(value))
        yield

def set(self, changes: Mapping[str, Any] | None = None, /, **kwargs: Any) -> None:
    """Update fields or groups from a mapping and keyword arguments.

    Nested groups accept mapping values and forward them to the nested
    config's own `set()` method.
    """
    if changes is not None:
        kwargs.update(changes)
    for name, value in kwargs.items():
        var: BaseConfig | Var[Any] = self._get_field_or_group(name)
        var.set(value)

def to_dict(self) -> dict[str, Any]:
    """Serialize the current config tree to nested dictionaries."""
    result: dict[str, Any] = {}
    for name in self._fields:
        result[name] = self._get_field(name).get()
    for name in self._groups:
        result[name] = self._get_group(name).to_dict()
    return result

def to_namespace(self) -> types.SimpleNamespace:
    """Serialize the current config tree to nested namespaces."""
    result: types.SimpleNamespace = types.SimpleNamespace()
    for name in self._fields:
        setattr(result, name, self._get_field(name).get())
    for name in self._groups:
        setattr(result, name, self._get_group(name).to_namespace())
    return result

@staticmethod
def add_separators(items: Iterable[WrappedItem]) -> list[WrappedItem]:
    """Add repr-style spacing and trailing commas to a sequence of items."""
    items: list[WrappedItem] = list(items)
    for i, item in enumerate(items):
        if i > 0:
            item.prefix = SPACE
        if i < len(items) - 1:
            item.suffix = COMMA
    return items

def container(
    self,
    obj: Any,
    begin: Text,
    children: Iterable[WrappedItem],
    end: Text,
    indent: Text | None = None,
    *,
    add_separators: bool = True,
    empty: Text | None = None,
    referencable: bool = True,
) -> WrappedContainer:
    """Build a repr-like container node.

    Args:
        obj: Original object represented by the container.
        begin: Opening punctuation, usually styled Rich text such as `(` or `[`.
        children: Wrapped child items to render inside the container.
        end: Closing punctuation.
        indent: Indentation used for wrapped layouts. Defaults to the active
            formatter option.
        add_separators: When `True`, add repr-style spaces and commas between
            children before building the container.
        empty: Alternate rendering for empty containers such as `set()`.
        referencable: Whether repeated appearances of `obj` should be rendered as
            shared references later in the pipeline.

    Returns:
        A wrapped container ready for tracing and lowering.

    Note:
        Containers are referencable by default. Repeated appearances of the
        same container can therefore render as shared-reference tags later
        in the pipeline.
    """
    if indent is None:
        indent: Text = self.options.indent
    if add_separators:
        children: list[WrappedItem] = self.add_separators(children)
    kwargs: dict[str, Any] = {}
    if empty is not None:
        kwargs["empty"] = empty
    return WrappedContainer(
        begin=begin,
        children=children,
        end=end,
        indent=indent,
        identifier=self.identifier(obj),
        referencable=referencable,
        **kwargs,
    )

def ellipsis_item(self) -> WrappedItem:
    """Return the positional ellipsis item used for truncated containers."""
    return WrappedPositionalItem.ellipsis()

def finish(self) -> LowerContext:
    """Build the lowering context with disambiguated type names."""
    return LowerContext(typenames=disambiguate_typenames(self.types))

def identifier(self, obj: Any) -> ObjectIdentifier:
    """Return the identity record for `obj`."""
    return ObjectIdentifier.from_obj(obj)

def key_value(self, key: Any, value: Any) -> WrappedItem:
    """Build a `key: value` item or an ellipsis placeholder when truncated."""
    if key is TRUNCATED or value is TRUNCATED:
        return self.ellipsis_item()
    return WrappedKeyValueItem(key=self.wrap_lazy(key), value=self.wrap_lazy(value))

def leaf(self, obj: Any, text: Text, *, referencable: bool = True) -> WrappedLeaf:
    """Build a scalar leaf node from Rich text.

    Set `referencable=False` for scalar summaries that should always render
    inline instead of turning into shared-reference tags.
    """
    return WrappedLeaf(
        value=text, identifier=self.identifier(obj), referencable=referencable
    )

def name_value(self, name: str | Text | None, value: Any) -> WrappedItem:
    """Build a repr-style `name=value` item.

    Falsey names fall back to [`positional`][liblaf.pretty.custom.PrettyContext.positional].
    """
    if not name:
        return self.positional(value)
    if isinstance(name, str):
        name = Text(name, "repr.attrib_name")
    return WrappedNameValueItem(name=name, value=self.wrap_lazy(value))

def positional(self, value: Any) -> WrappedItem:
    """Build a positional item or an ellipsis placeholder when truncated."""
    if value is TRUNCATED:
        return self.ellipsis_item()
    return WrappedPositionalItem(value=self.wrap_lazy(value))

@staticmethod
def possibly_sorted[T](
    items: Iterable[T],
    *,
    key: Callable[[T], Any] | None = None,
    reverse: bool = False,
) -> Iterable[T]:
    """Sort items when possible, otherwise preserve their original order.

    This keeps set- and dict-like output stable when the items are
    orderable, while still handling unorderable objects gracefully.
    """
    try:
        return sorted(items, key=key, reverse=reverse)
    except Exception:  # noqa: BLE001
        return items

def trace(self, root: WrappedNode) -> TracedNode:
    """Trace wrapped nodes and attach reference information."""
    children, traced_root = root.trace(self)
    queue: deque[WrappedChild] = deque(children)
    while queue:
        wrapped, self.depth, attach = queue.popleft()
        children, traced = wrapped.trace(self)
        queue.extend(children)
        attach(traced)
    return traced_root

def truncate_dict[K, V](
    self, items: Iterable[tuple[K, V]]
) -> Generator[tuple[K, V]]:
    """Yield mapping items up to `max_dict`, then a truncation marker."""
    for i, item in enumerate(items):
        if i >= self.options.max_dict:
            yield TRUNCATED, TRUNCATED
            break
        yield item

def truncate_list[T](self, items: Iterable[T]) -> Generator[T]:
    """Yield list-like items up to `max_list`, then a truncation marker."""
    for i, item in enumerate(items):
        if i >= self.options.max_list:
            yield TRUNCATED
            break
        yield item

def wrap_eager(self, obj: Any) -> WrappedNode:
    """Wrap `obj` immediately and memoize the result by object identity.

    This preserves shared references for referencable objects and avoids
    rebuilding the same wrapped node repeatedly during one pass.
    """
    id_: int = id(obj)
    if (wrapped := self.wrap_cache.get(id_)) is not None:
        return wrapped
    wrapped: WrappedNode = self.registry(obj, self)
    self.wrap_cache[id_] = wrapped
    return wrapped

def wrap_lazy(self, obj: Any) -> WrappedLazy:
    """Create a lazily wrapped placeholder for `obj`.

    Lazy children delay the actual wrapping work until the trace step asks
    for them.
    """
    return WrappedLazy(
        factory=lambda: self.wrap_eager(obj), identifier=self.identifier(obj)
    )

def __call__(self, obj: T, ctx: PrettyContext, /) -> WrappedNode | None: ...