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 any part (except the modifier) is omitted, the corresponding value in Quantity.default_format or Unit.default_format is filled in. If that is not set (it evaluates to False), UnitRegistry.default_format is used. 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.

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 [1]: ureg = pint.UnitRegistry()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

In [17]: f"{u}"  # default: default
Out[17]: '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

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 [18]: q = 1e-6 * u

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

In [20]: f"{q:~#P}"  # compact short pretty
Out[20]: '1.0 m·mg/s²'

In [21]: f"{q:P#~}"  # also compact short pretty
Out[21]: '1.0 m·mg/s²'

# additional magnitude format
In [22]: f"{q:.2f~#P}"  # short compact pretty with 2 float digits
Out[22]: '1.00 m·mg/s²'

In [23]: f"{q:#~}"  # short compact default
Out[23]: '1.0 m * mg / 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}")