Skip to content

Why formatting is one engine¤

There are four ways to turn a value into a string: repr, str, __format__, and the representations Jupyter asks for. They share one spec vocabulary and one entry point, and most of them share the renderer as well. The constructor form repr produces is the exception, for reasons below. This page is about why that is worth doing and what it cost.

For the spec vocabulary itself, see Format spec grammar. To make a type of your own formattable, see How to make a type formattable.

Why one renderer and not four¤

Four renderers means four places a change has to land, and nothing to stop them drifting. A route that wraps or adapts another route's string can only assume what shape that string has — that a repr already carries its own $…$, say, so the wrapper can be sliced back off. The assumption holds for the types it was written against and quietly eats real characters from the rest, and nothing in a four-renderer design keeps it in step with what the other three produce.

So a type no longer says how it renders. It says what it is made of: a tree of labelled fragments, returned from pparts. Each output route lays that same tree out differently. Add a markup and every type gets it. Register a type and it gets every markup, including ones added later by somebody else.

>>> from wadler_lindig_parts.examples import Version

>>> v = Version(2, 1)
>>> repr(v), f"{v:html}", f"{v:latex}"
('2.1', '<span>2</span>.<span>1</span>', '$2.1$')

One pparts method produced all three, and no route read another route's output. A markup wraps the fragments it is handed, so it has no string to slice and nothing to assume about one.

The cost is indirection. A hand-written _repr_latex_ shows you the whole story; a call into a renderer does not, and the story is spread across the fragment tree, the markup table and the layout. That is a real loss, paid once, against four paths that can no longer disagree.

Why the spec grammar scans left to right¤

A spec is a run of keywords that may end in a Python format spec: mul-html-.2f. The obvious way to parse that is to split on - and sort the pieces into keywords and leftovers. It does not work, because a Python format spec can contain - itself — as a sign flag in -.2f, or as a fill character in ->10.2f. Split on - and ->10.2f becomes two tokens, neither of which means anything.

So the scan is strictly left to right and stops looking for keywords at the first token that is not one. Everything after that point is the format spec, - and all. No token needs to be examined for what it might be; its position settles it.

>>> from wadler_lindig_parts import parse_spec

>>> parse_spec("mul-->10.2f")["value"]
'->10.2f'

The same choice is why no registered name may contain -. The split happens before any lookup, so a name carrying one could never be resolved, and the qualified axis=word form does not rescue it because that is split first too. A character the parser has already spent cannot be lent back to a name, which is why registration refuses it outright rather than discouraging it (Reserved characters).

The price is one rule the reader has to carry: the format spec goes last. mul-.2f-html does not fail with "unexpected keyword after format spec" — it cannot, because by then there are no keywords, only the string .2f-html, which is simply not a valid format spec. The alternative designs are worse: a delimiter other than - would make the common cases uglier, and sniffing each token for format-spec-ness would make adding a keyword able to change what an existing spec means.

Why keywords share one namespace¤

latex names a markup. mul names a separator style. Neither says which axis it belongs to, so a run can be written in any order: html-mul and mul-html are the same request.

The cost arrives when two packages want one word. dim could as reasonably mean a unit's dimension or a manifold's dimensionality. Both readings are right, and a flat namespace cannot hold both.

The way out is that axis=word is always available, and is in fact the real form: a keyword sets an axis to a value, so units_dim=dim is the operation spelled out and bare dim is shorthand for it. A bare word resolves while exactly one axis claims it; when two do, it raises and names both ways to disambiguate. Because that is per token, a collision costs one word in one spec — latex-mul-units_dim=dim-.3f — rather than a rewrite. A package that expects to share vocabulary can write the explicit form from the start and never be affected.

Note what this rules out. Refusing the second registration would be louder, and it is tempting now that the registrants are separate distributions. But then there is no second axis for axis=word to resolve to, and a shared word becomes a defeat rather than an inconvenience. The ambiguity is held open on purpose.

One name genuinely cannot be shared: an alias's. An alias expands to a whole spec rather than setting an axis, so there is no axis=word form for it to fall back on, and a word claimed by both an axis and an alias would have no resolved reading at all. That is the one case registration refuses outright (Registration rules), and it is refused for the same reason the others are allowed: the escape hatch is what makes sharing survivable, so a collision that cannot reach it is not worth holding open.

The alternative, namespacing every keyword by its axis from the beginning, would have made every ordinary spec longer to pay for a collision that has not happened yet.

Why the constructor form is not built from fragments¤

Every rendering but one is assembled from the fragments a type reports through pparts. The call layout is the exception: it hands off to wadler_lindig.pformat, which uses the type's own __pdoc__.

The two forms answer different questions. product layout shows what a value is — 2.0 * x. The call layout shows how to rebuild it — Term(coeff=2.0, symbol='x'). Only the type knows the second, and knowing it takes more than knowing how the value looks.

Point is the clearest case. It registers no pparts and inherits no mixin — it has told this engine nothing at all:

>>> import dataclasses
>>> from wadler_lindig_parts import pspec
>>> from wadler_lindig_parts.examples import Point

>>> dataclasses.is_dataclass(Point)
True
>>> pspec(Point(1.0, 2.0), "call")
'Point(x=1.0, y=2.0)'

That worked because wadler_lindig gives a dataclass a usable __pdoc__ for free, and the call layout delegates to it. A renderer working from display fragments could not have produced it: it would have had to know that Point takes x and y by keyword, in that order, under those names — which is constructor knowledge, not display knowledge.

The delegation has a consequence worth being explicit about: call layout asks for __pdoc__, and ReprMixin supplies a __pdoc__ built from fragments. So a type using the mixin with a product spec gets the fragment form under call too, while a plain dataclass gets the constructor form:

>>> from wadler_lindig_parts.examples import Term

>>> pspec(Term(2.0, "x"), "call")       # ReprMixin's own __pdoc__
'2.0 * x'
>>> pspec(Point(1.0, 2.0), "call")      # wadler-lindig's dataclass __pdoc__
'Point(x=1.0, y=2.0)'

That is not an inconsistency; it is the delegation working. call means "ask the type", and the two types answer differently because they have told wadler_lindig different things.

A type whose repr should be a constructor expression says so with a call spec. If it is a dataclass, the mixin then steps aside and wadler-lindig's field layout answers, so the mixin and a plain dataclass agree:

>>> import dataclasses
>>> from wadler_lindig_parts import PPart, ReprMixin, pparts

>>> @dataclasses.dataclass(repr=False)
... class Span(ReprMixin):
...     __repr_spec__ = "call"
...     lo: float
...     hi: float

>>> @pparts.dispatch
... def _(obj: Span, /, *, markup="text", **kw):
...     return (PPart("lo", str(obj.lo)), PPart("to", " to ", "sep"), PPart("hi", str(obj.hi)))

>>> Span(0.0, 1.0)
Span(lo=0.0, hi=1.0)
>>> f"{Span(0.0, 1.0):bare}"
'0.0 to 1.0'

A type that is not a dataclass has no field layout to fall back to, so it writes its own __pdoc__.

Which answer the mixin gives depends on its own __repr_spec__, not on the spec a caller passes: f"{x:call}" asks the type, and only a type whose spec is call answers with its constructor. In a notebook such a type shows its repr, because a constructor expression has no HTML or LaTeX form:

>>> Span(0.0, 1.0)._repr_html_() is None
True

So eval(repr(x)) == x stays a promise each type keeps for itself rather than one the renderer makes on every type's behalf. The names in such a repr have to be in scope for eval to resolve them, which is a constraint only the type can reason about.

Why an inert axis is allowed to do nothing¤

A spec can be accepted and change nothing. Asking for mul on a Version still renders 2.1, because a version's own . separator is a sep fragment and the sep axis leaves those alone:

>>> f"{v:mul}"
'2.1'
>>> f"{v:bare}"
'2.1'

This could have been an error, and there is a case for it: a spec that does nothing is usually a mistake, and silence is how mistakes survive. But erroring would break composite types, which depend on that same forwarding. An Interval of two Terms does not know the value axis exists; it passes the axes it does not handle down to its parts, and a format spec reaches the nested terms. A type cannot declare in advance which axes it honours, because the honest answer depends on the value.

So whether an axis mattered is settled by experiment rather than by declaration — render again with the axis reset to its default and see whether the output moves. inert_axes does exactly that:

>>> from wadler_lindig_parts import inert_axes, parse_spec, render

>>> spec = parse_spec("mul")
>>> inert_axes(v, spec, render(v, spec))
['sep']

It reports sep because asking for mul genuinely changed nothing here. It is a call you make while debugging rather than a setting, because each check costs a second render.

Why the engine is a package of its own¤

This package holds the fragments, the markups, the parser, the layouts and the axis registry, and knows nothing about quantities. unxt holds the axes it contributes to the grammar, and depends on this package for the rest.

The line is drawn there because coordinax and galax need the same machinery. The alternative is for each to depend on unxt for its string formatting, which makes unxt a dependency of packages with nothing else to do with units.

A claim like "imports nothing domain-specific" decays the moment someone adds a convenient import, so it is enforced rather than written down: a test parses every module in this package and fails if anything outside wadler_lindig, plum and the standard library appears. There are exactly two runtime dependencies, and adding a third means deleting that test, which a reviewer sees.

unxt, coordinax and galax register into this package as peers. There is no privileged set of axes, and an axis added downstream is read out of a spec exactly like a built-in one. Being peers across a distribution boundary makes three rules contract rather than implementation detail: the registry's collision behaviour, the refusal of a malformed markup row, and the moment __repr_spec__ is resolved. Each has a test pinning it, for that reason.

Why the layout is not ours¤

parts_to_doc returns a wadler_lindig document, not a string. Where a line breaks, how far a continuation is indented, and how a value nests inside a larger value are decided by wadler_lindig afterwards. This package decides only what the fragments are and what roles they carry.

The reason is that breaking lines well is harder than it looks. Given a nested structure, you want the outermost group that still fits on one line to stay on one line, and every group containing it to break — which is the problem the Wadler–Lindig algorithm solves. Solving it again here would mean solving it once per markup, with a separate set of bugs each time.

Handing the document over also settles one question that would otherwise be easy to get wrong: whether a markup's wrapper text costs columns. It does not. The <span> tags are emitted zero-width, so the same value breaks in the same place no matter which markup asked for it:

>>> from wadler_lindig_parts import doc_to_str, parts_to_doc, pparts
>>> from wadler_lindig_parts.examples import Term

>>> t = Term([1.0, 2.0, 3.0], "metres")
>>> print(doc_to_str(parts_to_doc(pparts(t), markup="text"), 20))
[1.0, 2.0, 3.0] *
  metres
>>> parts = pparts(t, markup="html")
>>> print(doc_to_str(parts_to_doc(parts, markup="html"), 20))
<span>[1.0, 2.0, 3.0]</span> *
  <span>metres</span>

The HTML line is 50 characters wide and the text line is 24, but both break after the * and indent metres by two, because only the visible content was measured against the width of 20. So you can reason about where a value will wrap without knowing which markup will render it — and a markup added later gets that behaviour without asking for it.

What this costs is control. You cannot tune the breaking from this side: a payload is atomic, so no width narrower than [1.0, 2.0, 3.0] will split it, and a library that wants to break inside its own values has to emit more fragments rather than request a different layout.

For the behaviour on its own, without the argument, see width and indent.