1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
Creating your own Measure Class
===============================
You can create your own measures easily by subclassing either
``measurement.base.MeasureBase`` or ``measurement.base.BidimensionalMeasure``.
Simple Measures
---------------
If your measure is not a measure dependent upon another measure (e.g speed,
distance/time) you can create new measurement by creating a subclass of
``measurement.base.MeasureBase``.
A simple example is Weight:
.. code-block:: python
from measurement.base import MeasureBase
class Weight(MeasureBase):
STANDARD_UNIT = 'g'
UNITS = {
'g': 1.0,
'tonne': 1000000.0,
'oz': 28.3495,
'lb': 453.592,
'stone': 6350.29,
'short_ton': 907185.0,
'long_ton': 1016000.0,
}
ALIAS = {
'gram': 'g',
'ton': 'short_ton',
'metric tonne': 'tonne',
'metric ton': 'tonne',
'ounce': 'oz',
'pound': 'lb',
'short ton': 'short_ton',
'long ton': 'long_ton',
}
SI_UNITS = ['g']
Important details:
* ``STANDARD_UNIT`` defines what unit will be used internally by the library
for storing the value of this measurement.
* ``UNITS`` provides a mapping relating a unit of your ``STANDARD_UNIT`` to
any number of defined units. In the example above, you will see that
we've established ``28.3495 g`` to be equal to ``1 oz``.
* ``ALIAS`` provides a list of aliases mapping keyword arguments to ``UNITS``.
these values are allowed to be used as keyword arguments when either creating
a new unit or guessing a measurement using ``measurement.utils.guess``.
* ``SI_UNITS`` provides a list of units that are SI Units. Units in this list
will automatically have new units and aliases created for each of the main
SI magnitudes. In the above example, this causes the list of ``UNITS``
and ``ALIAS`` es to be extended to include the following units (aliases):
``yg`` (yottagrams), ``zg`` (zeptograms), ``ag`` (attograms),
``fg`` (femtograms), ``pg`` (picograms), ``ng`` (nanograms),
``ug`` (micrograms), ``mg`` (milligrams), ``kg`` (kilograms),
``Mg`` (megagrams), ``Gg`` (gigagrams), ``Tg`` (teragrams),
``Pg`` (petagrams), ``Eg`` (exagrams), ``Zg`` (zetagrams),
``Yg`` (yottagrams).
Using formula-based conversions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some situations, your conversions between units may not be simple enough
to be accomplished by using simple conversions (e.g. temperature); for
situations like that, you should use ``sympy`` to create expressions relating
your measure's standard unit and the unit you're defining:
.. code-block:: python
from sympy import S, Symbol
from measurement.base import MeasureBase
class Temperature(MeasureBase):
SU = Symbol('kelvin')
STANDARD_UNIT = 'k'
UNITS = {
'c': SU - S(273.15),
'f': (SU - S(273.15)) * S('9/5') + 32,
'k': 1.0
}
ALIAS = {
'celsius': 'c',
'fahrenheit': 'f',
'kelvin': 'k',
}
Important details:
* See above 'Important Details' under `Normal Measures`.
* ``SU`` must define the symbol used in expressions relating your measure's
``STANDARD_UNIT`` to the unit you're defining.
Bi-dimensional Measures
-----------------------
Some measures are really just compositions of two separate measures -- Speed,
being a measure of the amount of distance covered over a unit of time, is one
common example of such a measure.
You can create such measures by subclassing
``measurement.base.BidimensionalMeasure``.
.. code-block:: python
from measurement.base import BidimensionalMeasure
from measurement.measures.distance import Distance
from measurement.measures.time import Time
class Speed(BidimensionalMeasure):
PRIMARY_DIMENSION = Distance
REFERENCE_DIMENSION = Time
ALIAS = {
'mph': 'mi__hr',
'kph': 'km__hr',
}
Important details:
* ``PRIMARY_DIMENSION`` is a class that measures the variable dimension of
this measure. In the case of 'miles-per-hour', this would be the 'miles'
or 'distance' dimension of the measurement.
* ``REFERENCE_DIMENSION`` is a class that measures the unit (reference)
dimension of the measure. In the case of 'miles-per-hour', this would be
the 'hour' or 'time' dimension of the measurement.
* ``ALIAS`` defines a list of convenient abbreviations for use either when
creating or defining a new instance of this measurement. In the above case,
you can create an instance of speed like ``Speed(mph=10)`` (equivalent to
``Speed(mile__hour=10)``) or convert to an existing measurement (
``speed_measurement``) into one of the aliased measures by accessing
the attribute named -- ``speed_measurement.kph`` (equivalent to
``speed_measurement.kilometer__hour``).
.. note::
Although unit aliases defined in a bi-dimensional measurement's ``ALIAS``
dictionary can be used either as keyword arguments or as attributes used
for conversion, unit aliases defined in simple measurements (those
subclassing ``measurement.base.MeasureBase``) can be used only as keyword
arguments.
|
