custom unit formats

[keewis]

This adds a register_unit_format function and implements the currently available formats using that. I'd also like to switch the siunitx code ("Lx") to use the new format, but because that is implemented in a function that expects a Unit object instead of a UnitContainer I still need to figure out a way to make it compatible.

I also renamed the default "" format to "D".

• Closes formats, documentation and custom formats #1357, closes Format without space between magnitude and unit #1370 (possibly more)
• Executed pre-commit run --all-files with no errors
• The change is fully covered by automated unit tests
• Documented in docs/ as appropriate
• Added an entry to the CHANGES file

[keewis]

this currently fails because Measurements.__format__ assumes dicts in _FORMATS. I guess we should probably move that code to a branch in formatter.

[keewis]

actually, maybe this is a case for the Quantity format (which would require register_quantity_format): Measurement is a subclass of Quantity, so the code should not relate to the unit format.

Since it's pretty difficult to do that without breaking anything, I renamed the dict of callables to _FORMATTERS and added back the dict of dict structure for _FORMATS.

[keewis]

this still needs proper documentation (e.g. there should be a complete list of formats available, with examples), but I guess that depends on #972

[keewis]

I just noticed that _parse_spec really is for quantity format specs, so format_unit doesn't really need the additional complexity.

The tests fail because siunitx_format_unit, which I decided to call from the registered format_latex_siunitx, needs a registry. Not sure how to fix that, maybe by adding a _registry field to UnitsContainer?

[hgrecco]

Regarding siunitx_format_unit The way we have solve this issues in the past is having a registry parameter. It might make sense here.

[keewis]

this is executed twice (once for pint.formatting.register_unit_format and once for pint.register_unit_format), and because there's no isolation in between the runs, the second run will try to register a pre-existing name. Not sure how to avoid that... does sphinx have a test isolation feature, or should we switch to python -m pytest --doctest-modules and the ipython / jupyter sphinx directives?

[keewis]

as far as I can tell, there's not much we can do here, except switching the doctest runner to pytest (and the doctest blocks in the rst files to ipython / jupyter-execute), to replace autodoc with autosummary, or to make sure autodoc does not generate pages for both pint.register_unit_format and pint.formatting.register_unit_format.

Since all of these are out-of-scope for this PR, I'll convert the example to a code block and we can discuss further changes in a dedicated issue / PR.

[hgrecco]

Yes, there is no way out.

[jules-ch]

Good work @keewis looks promising. 👍

[keewis]

I didn't bring this up before, but I basically disallowed passing quantity modifiers (just # for now) to Unit.__format__. So

f"{u:#C}"

is a error, but

ureg.default_format = "#C"
f"{u}"

is fine.

This might be a breaking change (it caused a few tests to fail in pint-xarray, but I think I'll just remove those) so it would be good to discuss this. For reference, ignoring those is as simple as calling extract_custom_formats on spec in Unit.__format__, just as we do with default_format.

Edit: if we choose to keep the breaking change I think we should improve the error message: #C is not a format specification could be more informative