Metadata-Version: 2.5
Name: wadler-lindig-parts
Version: 0.2.0
Summary: A parts layer over wadler-lindig: one engine behind repr, str, format and markup.
Project-URL: repository, https://github.com/GalacticDynamics/wadler-lindig-parts
Author-email: Nathaniel Starkman <nstarman@users.noreply.github.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: formatting,pretty-printing,repr,wadler-lindig
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: plum-dispatch>=2.7.0
Requires-Dist: wadler-lindig>=0.1.8
Description-Content-Type: text/markdown

# wadler-lindig-parts

A parts layer over [`wadler-lindig`][wl]: one engine behind `repr`, `str`,
`__format__` and the representations Jupyter asks for.

A type joins in by saying what it is *made of*, not how it renders. Register
`pparts` and the type gets every markup, every value form and the value
format spec — including axes added later by somebody else.

```python
>>> import dataclasses
>>> from wadler_lindig_parts import PPart, pparts, pspec

>>> @dataclasses.dataclass
... class Version:
...     major: int
...     minor: int
...
...     def __repr__(self) -> str:
...         return pspec(self, "bare")
...
...     def __format__(self, spec: str, /) -> str:
...         return pspec(self, spec)

>>> @pparts.dispatch
... def _(obj: Version, /, *, markup="text", **kw):
...     return (
...         PPart("major", str(obj.major)),
...         PPart("dot", ".", "sep"),
...         PPart("minor", str(obj.minor)),
...     )

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

```

One `pparts` method, two lines of plumbing, and four output routes that
cannot disagree.

`ReprMixin` writes those two methods for you and adds `__str__`, the Jupyter
hooks and a `__pdoc__`. Most types do not need a base class for two short
methods, so the examples here write them out; see
[how to make a type formattable][howto] for both routes side by side.

## Install

```bash
pip install wadler-lindig-parts
```

Two runtime dependencies, `wadler-lindig` and `plum-dispatch`, and nothing
else — ever. A test parses every module and fails on any import outside that
set plus the standard library, so a third dependency cannot be added without
someone deliberately deleting that test.

## Register axes before defining classes that name them

This one is about `ReprMixin`, which resolves `__repr_spec__` when the
**class is created**, not at first print. So a spec naming an axis or alias
that is not yet registered fails at the `class` statement:

```python
>>> from wadler_lindig_parts import Axis, ReprMixin, register_axis, unregister_axis

>>> try:
...     class TooEarly(ReprMixin):
...         __repr_spec__ = "call-vecform"
... except ValueError as e:
...     print("class creation failed:", str(e).split(":")[0])
class creation failed: invalid format spec 'call-vecform'

>>> _ = register_axis(Axis(
...     name="vector_form",
...     keywords={"vecform": True},
...     default=False,
...     layouts={"call": lambda v: {"vector_form": v}},
... ))
>>> class NowFine(ReprMixin):
...     __repr_spec__ = "call-vecform"
>>> NowFine._repr_spec_parsed["vector_form"]
True
>>> unregister_axis("vector_form")

```

Inside one package that was a statement about the order of lines in an
`__init__.py`. Between two installed distributions it is **load order between
them**: register your axes at import of your own package, before importing or
defining the classes whose repr specs use them. The error arrives at a `class`
statement that looks unrelated to the registration, which is why it is written
down here rather than left to the message.

A spec written inside `__repr__` is parsed on each call instead, so the plain
route has no ordering requirement: the same mistake surfaces at the first
print, naming the spec.

## Keywords share one flat namespace

Every registering distribution writes into the same keyword index, so a run of
keywords can be written in any order — `html-bare` and `bare-html` are the
same request. Two packages may want the same word, and both registrations
succeed: the bare word then raises and names both claimants, while `axis=word`
keeps working for each.

A collision therefore costs one word in one spec, not a rewrite and not a
registration. A package expecting to share vocabulary can write the qualified
form from the start.

## Documentation

<https://galacticdynamics.github.io/wadler-lindig-parts>

New to the package? [Make your first formattable
type](https://galacticdynamics.github.io/wadler-lindig-parts/tutorials/your-first-formattable-type/)
builds one from nothing in a few minutes. Already building something? The
[how-to guides](https://galacticdynamics.github.io/wadler-lindig-parts/how-to/)
are task-sized, and the
[reference](https://galacticdynamics.github.io/wadler-lindig-parts/reference/)
has the spec grammar and every public name.

[wl]: https://github.com/patrick-kidger/wadler-lindig
[howto]: https://galacticdynamics.github.io/wadler-lindig-parts/how-to/make-a-type-formattable/
