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".

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}")