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.