Skip to content

How to write a constructor-form repr¤

call layout prints how to rebuild a value. It does not go through pparts at all — it hands off to the object's own __pdoc__.

A dataclass already gets a working __pdoc__ from wadler_lindig, so you need this only when your type is not a dataclass, or when the one you get for free is not the constructor call you want.

For the product side — the fragments every markup is built from — see How to make a type formattable. The two are independent: a type may have both.

Implement __pdoc__¤

The protocol is __pdoc__(self, **kwargs) -> None | AbstractDoc. Build the document with wadler_lindig's own helpers so that nesting and line breaking keep working:

>>> import wadler_lindig as wl
>>> from wadler_lindig_parts import pspec

>>> class Interval:
...     def __init__(self, lo, hi):
...         self.lo, self.hi = lo, hi
...     def __pdoc__(self, **kwargs):
...         return wl.bracketed(
...             begin=wl.TextDoc("Interval("),
...             docs=wl.named_objs([("lo", self.lo), ("hi", self.hi)], **kwargs),
...             sep=wl.comma,
...             end=wl.TextDoc(")"),
...             indent=kwargs.get("indent", 2),
...         )

>>> iv = Interval(0.0, 1.0)
>>> pspec(iv, "call")
'Interval(lo=0.0, hi=1.0)'

named_objs renders each value with the same settings as the enclosing document, which is why **kwargs is forwarded rather than dropped.

The result is a document rather than a string, so it breaks under a narrow width without your doing anything:

>>> print(pspec(iv, "call", width=16))
Interval(
  lo=0.0, hi=1.0
)

If you only want to override sometimes¤

Return None and the default rendering is used instead. Anything that is not an AbstractDoc is ignored, so a method that returns early is handled by the same rule — there is no separate opt-out:

>>> class Maybe:
...     def __init__(self, n):
...         self.n = n
...     def __pdoc__(self, **kwargs):
...         if self.n < 0:
...             return None
...         return wl.TextDoc(f"Maybe({self.n})")

>>> pspec(Maybe(3), "call")
'Maybe(3)'
>>> pspec(Maybe(-1), "call")
'<...Maybe object at ...>'

If you want repr itself to use it¤

Write __repr__ as pspec(self, "call"), or inherit ReprMixin and set __repr_spec__ to a spec whose layout is call. The mixin is the shorter of the two here, because it derives __pdoc__ from the same spec:

>>> from wadler_lindig_parts import ReprMixin

>>> class Span(ReprMixin):
...     __repr_spec__ = "call"
...     def __init__(self, lo, hi):
...         self.lo, self.hi = lo, hi
...     def __pdoc__(self, **kwargs):
...         return wl.bracketed(
...             begin=wl.TextDoc("Span("),
...             docs=wl.named_objs([("lo", self.lo), ("hi", self.hi)], **kwargs),
...             sep=wl.comma,
...             end=wl.TextDoc(")"),
...             indent=kwargs.get("indent", 2),
...         )

>>> Span(0.0, 1.0)
Span(lo=0.0, hi=1.0)

If the renderer needs options of its own¤

wadler_lindig.pformat takes options that are not spec words, such as a custom= hook that lays out a value type its own way. Register them with render_options, the call layout's counterpart to pparts. It receives the spec, so an option can apply to some specs and not others; here the short form is kept out of array:

>>> import dataclasses
>>> from wadler_lindig_parts import render_options

>>> class Samples:
...     def __repr__(self):
...         return "Samples([0.1, 0.4, 0.2])"

>>> def short_samples(obj):
...     return wl.TextDoc("Samples(3)") if isinstance(obj, Samples) else None

>>> @dataclasses.dataclass(repr=False)
... class Run(ReprMixin):
...     __repr_spec__ = "call-type"
...     data: Samples

>>> @render_options.dispatch
... def _(obj: Run, /, *, spec):
...     return {"custom": short_samples} if spec["value"] == "type" else {}

>>> Run(Samples())
Run(data=Samples(3))
>>> f"{Run(Samples()):call-array}"
'Run(data=Samples([0.1, 0.4, 0.2]))'

spec is keyword-only, so plum dispatches on the object alone: a base class and a subclass can each register, however they annotate spec.

repr, str and format under call all use the options. They may only add arguments the spec does not control: returning width, indent or an axis's own argument such as short_arrays raises, because it would override what the caller asked for. Two limits: the options do not apply to product layouts, whose fragments come from pparts, and a wl.pformat that reaches the object from outside, as a field of another object, uses that outer call's options. Other option names are not checked, because wadler-lindig forwards unknown ones to every __pdoc__ it calls.

If your type is a dataclass¤

Do nothing. wadler_lindig already produces the constructor form, and a dataclass using ReprMixin with a call spec gets the same:

>>> from wadler_lindig_parts.examples import Point

>>> pspec(Point(1.0, 2.0), "call")
'Point(x=1.0, y=2.0)'

Note on axes¤

markup and sep do not apply under call — they are product-only, and naming one is an error rather than a silent no-op. width and indent do apply, as above. See Layout scoping.

See also¤