✨ feat(fmt): a string-formatting engine unifying repr, str, format, and the IPython reprs

[nstarman]

Closes #683.

Adds unxt._fmt: a shared engine behind repr, str, format, and the IPython
representations, so they agree on what an object is made of and a new type can
join in by registering one function.

>>> q = u.Q([1.0, 2, 3], "m")
>>> f"{q:mul}"        # '[1., 2., 3.] * m'
>>> f"{q:short}"      # 'f32[3] * m'
>>> f"{q:compact}"    # "Q([1., 2., 3.], unit='m')"
>>> f"{q:latex}"      # '$[1.,~2.,~3.] \; \mathrm{m}$'

How it works

A type registers pparts, returning a tree of roled fragments. Two consumers
turn that tree into output:

• parts_to_doc builds a wadler-lindig document, so plain-text rendering
  gets layout, line breaking, and nesting for free and composes inside a larger
  document. The engine feeds wadler-lindig rather than replacing it.
• parts_to_markup flattens to HTML or LaTeX. Those need no layout, and
  pushing markup through wadler-lindig would corrupt its width accounting — it
  measures len(ansi_strip(text)), so every <span> bills as visible columns
  (measured: 1.2×–2.2× inflation, misbreaking at the default width).

Three axes extend independently, each covered by a test: a new type
registers pparts; a new role needs nothing, since a fragment carries its
own plain-text fallback; a new markup is one MARKUPS row.

The module is private for now (unxt._fmt, not exported from unxt, not
in docs/api/). The engine is still settling and has not been exercised by a
downstream package yet, so it stays off the public surface until its shape is
proven. unxts.linalg reaches across into it to register pparts for
UnitsMatrix — a private cross-package import, tolerable while both live in
this workspace, and the first thing to revisit when it goes public.

Prototyped against the cases this has to grow into — an Angle carrying a
branch cut, a quantity with uncertainty, and a coordinax-shaped vector holding
components plus a frame and a chart.

Breaking change

repr/str of unit systems (see the 💥 boom commit):

	before	after
repr	unitsystem(kpc, ...) or LengthUnitSystem(length=Unit("km"))	unitsystem('kpc', 'Myr', 'solMass', 'rad')
str	LTMAUnitSystem(length, time, mass, angle)	unitsystem(kpc, Myr, solMass, rad)
dimension names	str	f"{usys:dims}"

repr now reconstructs the object: eval(repr(usys)) == usys holds for all
nine realizations. Two details are load-bearing, both found by testing the
property rather than assuming it — a single-unit system needs the list form
(unitsystem(['km']), since a lone string is a system name), and the
measured-constant realizations need a full-precision scale fallback because
to_string() truncates past six significant figures.

Downstream: galax has ~34 doctest lines that change (all nested
LTMAUnitSystem( length=Unit("kpc"), ...) inside potential reprs). It pins
unxt>=1.10.3 with no upper bound, so its CI goes red on release regardless of
merge order — that needs either a unxt<X cap added before release or a short
red window. A companion PR is not yet prepared. coordinax and potamides are
unaffected; neither asserts on unit-system rendering.

Bugs found here, fixed separately

Two of the bugs originally described as "fixed in passing" here have since
landed as their own PRs and are no longer part of this diff — this branch is
rebased on top of both:

1. __pdoc__ discarded a caller's custom= hook — fixed in 🐛 fix(quantity): stop __pdoc__ discarding a caller's custom= hook #869
   (merged). It assigned kwargs["custom"], and wadler_lindig.pdoc always
   puts custom in the kwargs it forwards, so the caller's was dropped on the
   default path.
2. _repr_latex_ corrupted QuantityMatrix — fixed in 🐛 fix(quantity): stop _repr_latex_ corrupting units without _repr_latex_ #870 (merged). It
   sliced [1:-1] assuming astropy's $...$ wrapping, so a UnitsMatrix
   (which has no _repr_latex_) lost its first and last characters:
   '$[1.,~2.,~3.] \; nitsMatrix("(m, s, kg)"$'. This PR's own pparts
   engine had the same assumption baked into its AbstractUnit rendering
   (to_string("latex")[1:-1]), so the 🐛 fix(fmt): strip $...$ only when the LaTeX fragment has them commit here carries the same hardening across
   into the new code path, via a shared unwrap_math helper.

One does not have a life outside this PR, since it's only meaningful once the
new repr exists:

3. repr=False on the unit-system dataclasses — without it the whole
   unit-system change is a silent no-op, since @dataclass plants a generated
   __repr__ in every subclass that shadows the base's, and every doctest
   keeps passing.

Notes for review

Sixteen commits after the rebase onto main (down from the original
seventeen — the standalone __pdoc__ fix dropped out as a no-op once #869
merged); the 💥 boom commit is the point of no return and could be split out
if you'd rather land the rest first.

Two design decisions worth a look, both argued in the commit messages: the
engine uses a module-local plum.Dispatcher (the global one keys on bare
__name__, so two libraries defining pparts would silently merge method
tables), and composites nest child parts rather than splicing them flat
(a wadler-lindig group is all-or-nothing, so splicing makes every break point
break together).

unxt._src.fmt is at 100% coverage, and pylint is at 10.00/10.

Milestone: set to v2.1.0 to match the two most recent PRs, but this
carries a breaking change — if you want strict semver that wants a major
milestone instead.

[nstarman]

@adrn the goal isn't to make a package called unxts.fmt but to develop this as a private implementation "in-house", then spin it off as a small utility package that unxt, coordinax, and galax can all use.

[Copilot]

Pull request overview

This PR introduces a new unxt.fmt formatting engine that unifies how repr, str, format, and IPython rich representations are produced, enabling new types to participate by registering a single pparts implementation. It also updates unit system rendering to ensure repr round-trips via eval(repr(usys)) == usys, and aligns documentation/tests with the new output.

Changes:

• Added unxt.fmt (public) and unxt._src.fmt (implementation) providing a parts-based formatting pipeline for text/HTML/LaTeX plus FORMAT_PRESETS for f-string specs (e.g. :compact, :mul, :latex).
• Reworked unit system rendering via a shared AbstractUnitSystem.__pdoc__, updated dataclass repr=False for all unit-system shapes, and added tests for repr round-tripping and readable str.
• Routed Quantity IPython markup reprs (_repr_html_, _repr_latex_) through the new engine and registered UnitsMatrix parts to preserve structure and prevent LaTeX slicing regressions.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/test_unitsystems.py	Adds property-style tests ensuring unit-system repr round-trips and str/dims formatting behaves as intended.
tests/unit/test_quantity_printing.py	Adds tests covering format presets and the __pdoc__ custom-hook chaining behavior.
tests/unit/test_fmt.py	New focused test suite for unxt.fmt presets, markup escaping, layout behavior, extensibility, and JIT interactions.
src/unxt/fmt.py	New public module re-exporting the formatting engine API.
src/unxt/_src/unitsystems/flags.py	Updates doctest outputs for unit-system rendering changes.
src/unxt/_src/unitsystems/core.py	Updates doctests and ensures dynamic unit-system dataclasses don’t shadow base rendering (repr=False).
src/unxt/_src/unitsystems/builtin.py	Switches built-in unit-system dataclasses to repr=False; adds DimensionlessUnitSystem.__pdoc__.
src/unxt/_src/unitsystems/base.py	Adds round-tripping unit-string logic and centralizes unit-system rendering in __pdoc__; updates __repr__, __str__, __format__.
src/unxt/_src/quantity/mixins.py	Routes IPython HTML/LaTeX repr methods through the new formatting engine.
src/unxt/_src/quantity/base.py	Fixes __pdoc__ custom hook clobbering by chaining hooks; routes __format__ through pspec; adds _chain_custom.
src/unxt/_src/fmt.py	New core formatting engine: parts tree model, doc/markup consumers, preset table, and fallback behavior.
src/unxt/init.py	Exposes fmt at the package top level.
README.md	Updates unit-system rendering examples to match new repr.
packages/unxts.linalg/tests/test_printing.py	Adds regression tests ensuring QuantityMatrix markup output is correct (esp. LaTeX).
packages/unxts.linalg/src/unxts/linalg/_src/_units_matrix.py	Registers UnitsMatrix with unxt.fmt.pparts to render structured unit tuples correctly.
packages/unxts.interop.gala/docs/index.md	Updates doctest output for unit-system rendering.
packages/unxts.interop.gala/docs/guide.md	Updates doctest output for unit-system rendering.
packages/unxts.interop.gala/docs/api.md	Updates doctest output for unit-system rendering.
docs/interop/dataclassish.md	Updates example output to reflect new str rendering of unit systems.
docs/index.md	Updates doctest outputs for unit systems to match new repr.
docs/guides/units_and_systems.md	Updates doctest outputs for unit systems to match new repr.
docs/api/index.md	Adds fmt to the API docs toctree.
docs/api/fmt.md	New API docs page for unxt.fmt.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.85%. Comparing base (6888db8) to head (affbc94).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #855      +/-   ##
==========================================
+ Coverage   99.82%   99.85%   +0.03%     
==========================================
  Files          84       86       +2     
  Lines        3985     4130     +145     
  Branches      311      333      +22     
==========================================
+ Hits         3978     4124     +146     
  Misses          3        3              
+ Partials        4        3       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.

[nstarman]

@adrn, if you like the look of this, I'll actually factor it out into a small companion utility library so that we can use this unified engine for unxt, coordinax, galax and the others.

I might try to get some stuff upstreamed into wadler_lindig, particularly a class so invisible elements like <span> don't get counted towards line length. This is one of a few things preventing further unification of the repr, html, and latex backends.