liblaf-pretty 0.2.0

Format Python objects as repr-like plain text or width-aware Rich renderables.

Explore the docs »

API Reference · Changelog · Report Bug

✨ Features

• Plain-text formatting for logs and snapshots, plus a Rich renderable path for width-aware console output.
• Built-in handling for common containers, fieldz-compatible models, and objects with __rich_repr__.
• Lazy summaries for NumPy, JAX, Torch, and Warp arrays when those libraries are already imported.
• Shared-reference and cycle tracking for referencable objects such as mappings, sets, frozensets, and custom containers.
• A small customization surface through __pretty__(), register_type(), register_func(), and register_lazy().
• Environment-backed defaults through PRETTY_*, with per-call overrides for logs, snapshots, tests, and interactive debugging.

📦 Installation

uv add liblaf-pretty
# or
pip install liblaf-pretty

🧪 Quick Start

Use pformat() when you want stable plain text:

from liblaf.pretty import pformat

print(pformat({"alpha": [1, 2, 3]}), end="")

{'alpha': [1, 2, 3]}

Use plower() when you want a Rich renderable whose layout is chosen later by the target Console. If you already have a console, use pprint() or its alias pp() for the print-now path.

🎛️ Configuration

The public formatting helpers accept per-call overrides for:

• max_level, max_list, max_array, max_dict
• max_string, max_long, max_other
• indent
• hide_defaults

Those values can also come from environment variables:

export PRETTY_MAX_LIST=2
export PRETTY_INDENT='[bold]>>[/] '

indent accepts plain text, Rich markup, ANSI-colored strings, or rich.text.Text.

🔢 Arrays

Array libraries are optional. Once NumPy, JAX, Torch, or Warp is already loaded, liblaf.pretty formats small arrays as compact dtype-and-shape summaries:

import numpy as np

from liblaf.pretty import pformat

print(pformat(np.zeros((2, 3), dtype=np.float32)), end="")

f32[2,3](numpy)

If any dimension is larger than max_array, the formatter falls back to the object's normal repr instead of importing or traversing large values.

🔁 Shared References

Repeated referencable objects are annotated on first appearance and then render as <Type @ hexid> references later in the output. Lists and tuples stay safe too, but they repeat their value instead of collapsing into a reference tag.

🧩 Custom Formatting

Reach for the smallest hook that matches the job:

• Implement __pretty__(self, ctx) when you own the class.
• Use register_type() for a concrete type and its subclasses.
• Use register_func() for structural matching.
• Use register_lazy() for optional dependencies that should only activate after their module is already imported.

PrettyContext gives custom formatters the builder helpers they usually need: ctx.container(), ctx.leaf(), ctx.positional(), ctx.name_value(), and ctx.key_value().

For the full walkthrough, see the custom formatter guide.

🛠️ Development

Common workflows:

mise run lint
mise run docs:build
mise run docs:serve
mise run gen:ref-pages
nox

nox runs the test matrix across Python 3.12, 3.13, and 3.14, with both highest and lowest-direct dependency resolution.

---

📝 License

Copyright © 2026 liblaf.
This project is MIT licensed.