String formatting

The conversion of Unit and Quantity 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][unit format]

where each part is optional and the order of these is arbitrary.

In case the format is omitted, the corresponding value in the object’s .default_format attribute (Quantity.default_format or Unit.default_format) is filled in. For example:

In [1]: ureg = pint.UnitRegistry()
   ...: ureg.default_format = "~P"
   ...: 

In [2]: u = ureg.Unit("m ** 2 / s ** 2")
   ...: f"{u}"
   ...: 
Out[2]: 'm²/s²'

In [3]: u.default_format = "~C"
   ...: f"{u}"
   ...: 
Out[3]: 'm**2/s**2'

In [4]: u.default_format, ureg.default_format
Out[4]: ('~C', '~P')

In [5]: q = ureg.Quantity(1.25, "m ** 2 / s ** 2")
   ...: f"{q}"
   ...: 
Out[5]: '1.25 m²/s²'

In [6]: q.default_format = ".3fP"
   ...: f"{q}"
   ...: 
Out[6]: '1.250 meter²/second²'

In [7]: q.default_format, ureg.default_format
Out[7]: ('.3fP', '~P')

Note

In the future, the magnitude and unit format spec will be evaluated independently, such that with a global default of ureg.default_format = ".3f" and f"{q:P} the format that will be used is ".3fP". This behavior can be opted into by setting UnitRegistry.separate_format_defaults to True.

If both are not set, the global default of "D" and the magnitude’s default format are used instead.

Note

Modifiers may be used without specifying any format: "~" is a valid format specification and is equal to "~D".

Unit Format Specifications

The Unit class ignores the magnitude format part, and the unit format consists of just the format type.

Let’s look at some examples:

In [8]: ureg = pint.UnitRegistry()

In [9]: u = ureg.kg * ureg.m / ureg.s ** 2

In [10]: f"{u:P}"  # using the pretty format
Out[10]: 'kilogram·meter/second²'

In [11]: f"{u:~P}"  # short pretty
Out[11]: 'kg·m/s²'

In [12]: f"{u:P~}"  # also short pretty
Out[12]: 'kg·m/s²'

# default format
In [13]: u.default_format
Out[13]: ''

In [14]: ureg.default_format
Out[14]: ''

In [15]: str(u)  # default: default
Out[15]: 'kilogram * meter / second ** 2'

In [16]: f"{u:~}"  # default: short default
Out[16]: 'kg * m / s ** 2'

In [17]: ureg.default_format = "C"  # registry default to compact

In [18]: str(u)  # default: compact
Out[18]: 'kilogram*meter/second**2'

In [19]: f"{u}"  # default: compact
Out[19]: 'kilogram*meter/second**2'

In [20]: u.default_format = "P"

In [21]: f"{u}"  # default: pretty
Out[21]: 'kilogram·meter/second²'

In [22]: u.default_format = ""  # TODO: switch to None

In [23]: ureg.default_format = ""  # TODO: switch to None

In [24]: f"{u}"  # default: default
Out[24]: 'kilogram * meter / second ** 2'

Unit Format Types

pint comes with a variety of unit formats:

Spec	Name	Example
D	default	kilogram * meter / second ** 2
P	pretty	kilogram·meter/second²
H	HTML	kilogram meter/second<sup>2</sup>
L	latex	\frac{\mathrm{kilogram} \cdot \mathrm{meter}}{\mathrm{second}^{2}}
Lx	latex siunitx	\si[]{\kilo\gram\meter\per\second\squared}
C	compact	kilogram*meter/second**2

Custom Unit Format Types

Using pint.register_unit_format(), it is possible to add custom formats:

In [25]: u = ureg.Unit("m ** 3 / (s ** 2 * kg)")

In [26]: @pint.register_unit_format("simple")
   ....: def format_unit_simple(unit, registry, **options):
   ....:     return " * ".join(f"{u} ** {p}" for u, p in unit.items())
   ....: 

In [27]: f"{u:~simple}"
Out[27]: 'm ** 3 * s ** -2 * kg ** -1'

where unit is a dict subclass containing the unit names and their exponents.

Quantity Format Specifications

The magnitude format is forwarded to the magnitude (for a unit-spec of H the magnitude’s _repr_html_ is called).

Let’s look at some more examples:

In [28]: q = 1e-6 * u

# modifiers
In [29]: f"{q:~P}"  # short pretty
Out[29]: '1×10⁻⁶ m³/kg/s²'

In [30]: f"{q:~#P}"  # compact short pretty
Out[30]: '0.9999999999999999 mm³/g/s²'

In [31]: f"{q:P#~}"  # also compact short pretty
Out[31]: '0.9999999999999999 mm³/g/s²'

# additional magnitude format
In [32]: f"{q:.2f~#P}"  # short compact pretty with 2 float digits
Out[32]: '1.00 mm³/g/s²'

In [33]: f"{q:#~}"  # short compact default
Out[33]: '0.9999999999999999 mm ** 3 / g / s ** 2'

Quantity Format Types

There are no special quantity formats yet.

Modifiers

Modifier	Meaning	Example
~	Use the unit’s symbol instead of its canonical name	kg·m/s² (f"{u:~P}")
#	Call Quantity.to_compact() first	1.0 m·mg/s² (f"{q:#~P}")