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

D

default

3.4e+09 kilogram * meter / second ** 2

P

pretty

3.4×10⁹ kilogram·meter/second²

H

HTML

3.4×10<sup>9</sup> kilogram meter/second<sup>2</sup>

L

latex

3.4\\times 10^{9}\\ \\frac{\\mathrm{kilogram} \\cdot \\mathrm{meter}}{\\mathrm{second}^{2}}

Lx

latex siunitx

\\SI[]{3.4e+09}{\\kilo\\gram\\meter\\per\\second\\squared}

C

compact

3.4e+09 kilogram*meter/second**2

These examples are using g` as numeric modifier. Measurement are also affected by these modifiers.

Quantity modifiers#

Modifier

Meaning

Example

#

Call Quantity.to_compact() first

1.0 m·mg/s² (f"{q:#~P}")

Unit modifiers#

Modifier

Meaning

Example

~

Use the unit’s symbol instead of its canonical name

kg·m/s² (f"{u:~P}")

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.

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.