String formatting specification¶
The conversion of Unit
, Quantity
and Measurement
objects to strings (e.g. through the str
builtin or f-strings) can be
customized using format specifications. The basic format is:
[magnitude format][modifier][pint format]
where each part is optional and the order of these is arbitrary.
>>> import pint
>>> ureg = pint.UnitRegistry()
>>> q = 2.3e-6 * ureg.m ** 3 / (ureg.s ** 2 * ureg.kg)
>>> f"{q:~P}" # short pretty
'2.3×10⁻⁶ m³/kg/s²'
>>> f"{q:~#P}" # compact short pretty
'2.3 mm³/g/s²'
>>> f"{q:P#~}" # also compact short pretty
'2.3 mm³/g/s²'
>>> f"{q:.2f~#P}" # short compact pretty with 2 float digits
'2.30 mm³/g/s²'
>>> f"{q:#~}" # short compact default
'2.3 mm ** 3 / g / s ** 2'
In case the format is omitted, the corresponding value in the formatter
.default_format
attribute is filled in. For example:
>>> ureg.formatter.default_format = "P"
>>> f"{q}"
'2.3×10⁻⁶ meter³/kilogram/second²'
Pint Format Types¶
pint
comes with a variety of unit formats. These impact the complete representation:
Spec |
Name |
Examples |
---|---|---|
|
default |
|
|
pretty |
|
|
HTML |
|
|
latex |
|
|
latex siunitx |
|
|
compact |
|
These examples are using g` as numeric modifier. Measurement
are also affected
by these modifiers.
Quantity modifiers¶
Modifier |
Meaning |
Example |
---|---|---|
|
Call |
|
Unit modifiers¶
Modifier |
Meaning |
Example |
---|---|---|
|
Use the unit’s symbol instead of its canonical name |
|
Magnitude modifiers¶
Pint uses the format specifications. However, it is important to remember that only the type honors the locale. Using any other numeric format (e.g. g, e, f) will result in a non-localized representation of the number.
Custom formats¶
Using pint.register_unit_format()
, it is possible to add custom
formats:
>>> @pint.register_unit_format("Z")
... def format_unit_simple(unit, registry, **options):
... return " * ".join(f"{u} ** {p}" for u, p in unit.items())
>>> f"{q:Z}"
'2.3e-06 kilogram ** -1 * meter ** 3 * second ** -2'
where unit
is a dict
subclass containing the unit names and
their exponents, registry
is the current instance of :py:class:UnitRegistry
and
options
is not yet implemented.
You can choose to replace the complete formatter. Briefly, the formatter if an object with the following methods: format_magnitude, format_unit, format_quantity, format_uncertainty, format_measurement. The easiest way to create your own formatter is to subclass one that you like.
>>> from pint.delegates.formatter.plain import DefaultFormatter
>>> class MyFormatter(DefaultFormatter):
...
... default_format = ""
...
... def format_unit(self, unit, uspec, sort_func, **babel_kwds) -> str:
... return "ups!"
...
>>> ureg.formatter = MyFormatter()
>>> ureg.formatter._registry = ureg
>>> str(q)
'2.3e-06 ups!'
By replacing other methods, you can customize the output as much as you need.