openstack/deb-python-pint

Martin Thoma f4ed37f39c Fixed some typos in the documentation; removed trailing slashes; broke some lines to make diffs easier; changed some hanging indentation according to PEP8

2015-04-04 09:48:39 +02:00

7.7 KiB

Raw Blame History

Tutorial

Converting Quantities

Pint has the concept of Unit Registry, an object within which units are defined and handled. You start by creating your registry:

>>> from pint import UnitRegistry
>>> ureg = UnitRegistry()

from pint import UnitRegistry ureg = UnitRegistry() Q = ureg.Quantity

If no parameter is given to the constructor, the unit registry is populated with the default list of units and prefixes. You can now simply use the registry in the following way:

>>> distance = 24.0 * ureg.meter >>> print(distance) 24.0 meter >>> time = 8.0 * ureg.second >>> print(time) 8.0 second >>> print(repr(time)) <Quantity(8.0, 'second')>

In this code distance and time are physical quantity objects (Quantity). Physical quantities can be queried for their magnitude, units, and dimensionality:

>>> print(distance.magnitude) 24.0 >>> print(distance.units) meter >>> print(distance.dimensionality) [length]

and can handle mathematical operations between:

>>> speed = distance / time >>> print(speed) 3.0 meter / second

As unit registry knows about the relationship between different units, you can convert quantities to the unit of choice:

>>> speed.to(ureg.inch / ureg.minute ) <Quantity(7086.614173228345, 'inch / minute')>

This method returns a new object leaving the original intact as can be seen by:

>>> print(speed) 3.0 meter / second

If you want to convert in-place (i.e. without creating another object), you can use the ito method:

>>> speed.ito(ureg.inch / ureg.minute ) <Quantity(7086.614173228345, 'inch / minute')> >>> print(speed) 7086.614173228345 inch / minute

If you ask Pint to perform an invalid conversion:

>>> speed.to(ureg.joule) Traceback (most recent call last): ... pint.pint.DimensionalityError: Cannot convert from 'inch / minute' (length / time) to 'joule' (length ** 2 * mass / time ** 2)

There are also methods 'to_base_units' and 'ito_base_units' which automatically convert to the reference units with the correct dimensionality:

>>> height = 5.0 * ureg.foot + 9.0 * ureg.inch >>> print(height) 5.75 foot >>> print(height.to_base_units()) 1.7526 meter >>> print(height) 5.75 foot >>> height.ito_base_units() >>> print(height) 1.7526 meter

In some cases it is useful to define physical quantities objects using the class constructor:

>>> Q = ureg.Quantity >>> Q(1.78, ureg.meter) == 1.78 * ureg.meter True

(I tend to abbreviate Quantity as Q_) The built-in parser recognizes prefixed and pluralized units even though they are not in the definition list:

>>> distance = 42 * ureg.kilometers >>> print(distance) 42 kilometer >>> print(distance.to(ureg.meter)) 42000.0 meter

If you try to use a unit which is not in the registry:

>>> speed = 23 * ureg.snail_speed Traceback (most recent call last): ... pint.pint.UndefinedUnitError: 'snail_speed' is not defined in the unit registry

You can add your own units to the registry or build your own list. More info on that defining

String parsing

Pint can also handle units provided as strings:

>>> 2.54 * ureg.parse_expression('centimeter') <Quantity(2.54, 'centimeter')>

or using the registry as a callable for a short form:

>>> 2.54 * ureg('centimeter') <Quantity(2.54, 'centimeter')>

or using the Quantity constructor:

>>> Q(2.54, 'centimeter') <Quantity(2.54, 'centimeter')>

Numbers are also parsed, so you can use an expression:

>>> ureg('2.54 * centimeter') <Quantity(2.54, 'centimeter')>

or:

>>> Q('2.54 * centimeter') <Quantity(2.54, 'centimeter')>

This enables you to build a simple unit converter in 3 lines:

>>> user_input = '2.54 * centimeter to inch' >>> src, dst = user_input.split(' to ') >>> Q(src).to(dst) <Quantity(1.0, 'inch')>

Warning

Pint currently uses eval under the hood. Do not use this approach from untrusted sources as it is dangerous.

String formatting

Pint's physical quantities can be easily printed:

>>> accel = 1.3 * ureg['meter/second*2'] >>> # The standard string formatting code >>> print('The str is {!s}'.format(accel)) The str is 1.3 meter / second* 2 >>> # The standard representation formatting code >>> print('The repr is {!r}'.format(accel)) The repr is <Quantity(1.3, 'meter / second ** 2')> >>> # Accessing useful attributes >>> print('The magnitude is {0.magnitude} with units {0.units}'.format(accel)) The magnitude is 1.3 with units meter / second ** 2

Note

In Python 2.6, unnumbered placeholders are invalid. Therefore you need to write {0} instead of {}, {0!s} instead of {!s} in string formatting operations.

But Pint also extends the standard formatting capabilities for unicode and LaTeX representations:

>>> accel = 1.3 * ureg['meter/second**2'] >>> # Pretty print >>> print('The pretty representation is {:P}'.format(accel)) 'The pretty representation is 1.3 meter/second²' >>> # Latex print >>> 'The latex representation is {:L}'.format(accel) 'The latex representation is 1.3 \frac{meter}{second^{2}}' >>> # HTML print >>> 'The HTML representation is {:H}'.format(accel) 'The HTML representation is 1.3 meter/second<sup>2</sup>'

Note

In Python 2, run from __future__ import unicode_literals or prefix pretty formatted strings with u to prevent UnicodeEncodeError.

If you want to use abbreviated unit names, prefix the specification with `~`:

>>> 'The str is {:~}'.format(accel) 'The str is 1.3 m / s ** 2' >>> print('The pretty representation is {:~P}'.format(accel)) The pretty representation is 1.3 m²/s

The same is true for latex (L) and HTML (H) specs.

Finally, you can specify a default format specification:

>>> 'The acceleration is {}'.format(accel) 'The acceleration is 1.3 meter / second ** 2' >>> ureg.default_format = 'P' >>> 'The acceleration is {}'.format(accel) 'The acceleration is 1.3 meter/second²'

Using Pint in your projects

If you use Pint in multiple modules within your Python package, you normally want to avoid creating multiple instances of the unit registry. The best way to do this is by instantiating the registry in a single place. For example, you can add the following code to your package `__init__.py`:

from pint import UnitRegistry
ureg = UnitRegistry()
Q_ = ureg.Quantity

Then in yourmodule.py the code would be:

from . import ureg, Q_

length = 10 * ureg.meter
my_speed = Q_(20, 'm/s')

If you are pickling and unplicking Quantities within your project, you should also define the registry as the application registry:

from pint import UnitRegistry, set_application_registry
ureg = UnitRegistry()
set_application_registry(ureg)