1Defining Quantities
2===================
3
4A quantity in Pint is the product of a unit and a magnitude.
5
6Pint supports several different ways of defining physical quantities, including
7a powerful string parsing system. These methods are largely interchangeable,
8though you may **need** to use the constructor form under certain circumstances
9(see :doc:`nonmult` for an example of where the constructor form is required).
10
11By multiplication
12-----------------
13
14If you've read the :ref:`Tutorial`, you're already familiar with defining a
15quantity by multiplying a ``Unit()`` and a scalar:
16
17.. doctest::
18
19    >>> from pint import UnitRegistry
20    >>> ureg = UnitRegistry()
21    >>> ureg.meter
22    <Unit('meter')>
23    >>> 30.0 * ureg.meter
24    <Quantity(30.0, 'meter')>
25
26This works to build up complex units as well:
27
28.. doctest::
29
30    >>> 9.8 * ureg.meter / ureg.second**2
31    <Quantity(9.8, 'meter / second ** 2')>
32
33
34Using the constructor
35---------------------
36
37In some cases it is useful to define :class:`Quantity() <pint.quantity.Quantity>`
38objects using it's class constructor. Using the constructor allows you to
39specify the units and magnitude separately.
40
41We typically abbreviate that constructor as `Q_` to make it's usage less verbose:
42
43.. doctest::
44
45    >>> Q_ = ureg.Quantity
46    >>> Q_(1.78, ureg.meter)
47    <Quantity(1.78, 'meter')>
48
49As you can see below, the multiplication and constructor methods should produce
50the same results:
51
52.. doctest::
53
54    >>> Q_(30.0, ureg.meter) == 30.0 * ureg.meter
55    True
56    >>> Q_(9.8, ureg.meter / ureg.second**2)
57    <Quantity(9.8, 'meter / second ** 2')>
58
59Quantity can be created with itself, if units is specified ``pint`` will try to convert it to the desired units.
60If not, pint will just copy the quantity.
61
62.. doctest::
63
64    >>> length = Q_(30.0, ureg.meter)
65    >>> Q_(length, 'cm')
66    <Quantity(3000.0, 'centimeter')>
67    >>> Q_(length)
68    <Quantity(30.0, 'meter')>
69
70Using string parsing
71--------------------
72
73Pint includes a powerful parser for detecting magnitudes and units (with or
74without prefixes) in strings. Calling the ``UnitRegistry()`` directly
75invokes the parsing function:
76
77.. doctest::
78
79    >>> 30.0 * ureg('meter')
80    <Quantity(30.0, 'meter')>
81    >>> ureg('30.0 meters')
82    <Quantity(30.0, 'meter')>
83    >>> ureg('3000cm').to('meters')
84    <Quantity(30.0, 'meter')>
85
86The parsing function is also available to the ``Quantity()`` constructor and
87the various ``.to()`` methods:
88
89.. doctest::
90
91    >>> Q_('30.0 meters')
92    <Quantity(30.0, 'meter')>
93    >>> Q_(30.0, 'meter')
94    <Quantity(30.0, 'meter')>
95    >>> Q_('3000.0cm').to('meter')
96    <Quantity(30.0, 'meter')>
97
98Or as a standalone method on the ``UnitRegistry``:
99
100.. doctest::
101
102   >>> 2.54 * ureg.parse_expression('centimeter')
103   <Quantity(2.54, 'centimeter')>
104
105It is fairly good at detecting compound units:
106
107.. doctest::
108
109    >>> g = ureg('9.8 meters/second**2')
110    >>> g
111    <Quantity(9.8, 'meter / second ** 2')>
112    >>> g.to('furlongs/fortnight**2')
113    <Quantity(7.12770743e+10, 'furlong / fortnight ** 2')>
114
115And behaves well when given dimensionless quantities, which are parsed into
116their appropriate objects:
117
118.. doctest::
119
120   >>> ureg('2.54')
121   2.54
122   >>> type(ureg('2.54'))
123   <class 'float'>
124   >>> Q_('2.54')
125   <Quantity(2.54, 'dimensionless')>
126   >>> type(Q_('2.54'))
127   <class 'pint.quantity.build_quantity_class.<locals>.Quantity'>
128
129.. note:: Pint's rule for parsing strings with a mixture of numbers and
130   units is that **units are treated with the same precedence as numbers**.
131
132For example, the units of
133
134.. doctest::
135
136   >>> Q_('3 l / 100 km')
137   <Quantity(0.03, 'kilometer * liter')>
138
139may be unexpected at first but, are a consequence of applying this rule. Use
140brackets to get the expected result:
141
142.. doctest::
143
144   >>> Q_('3 l / (100 km)')
145   <Quantity(0.03, 'liter / kilometer')>
146
147.. note:: Since version 0.7, Pint **does not** use eval_ under the hood.
148   This change removes the `serious security problems`_ that the system is
149   exposed to when parsing information from untrusted sources.
150
151.. _eval: http://docs.python.org/3/library/functions.html#eval
152.. _`serious security problems`: http://nedbatchelder.com/blog/201206/eval_really_is_dangerous.html
153