Newer
Older
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
Physical Quantities
===================
This package provides types for representing physical quantities, which have a magnitude and
a unit.
An in-depth usage guide is available in the module's docstring.
Quick Start
-----------
Create units by creating an enum class subclassing `QuantityUnit`. The value of each item
is scaled to its siblings, with an appropriate value chosen as the smallest representable
quantity which forms the base precision when scaling quantities. For example, units of
distance where the smallest possible quantity is 0.1mm:
```python
from kodo.quantities import QuantityUnit
class Distance(QuantityUnit):
MILLIMETERS = 10
CENTIMETERS = 10 * MILLIMETERS
METERS = 100 * CENTIMETERS
KILOMETERS = 1000 * METERS
SIXTEENTH_INCH = 15 # 1/16" == 1.5mm
QUARTER_INCH = 4 * SIXTEENTH_INCH
HALF_INCH = 8 * SIXTEENTH_INCH
INCH = 16 * SIXTEENTH_INCH
FOOT = 12 * INCH
class Time(QuantityUnit):
MILLISECONDS = 1
SECONDS = 1000 * MILLISECONDS
MINUTES = 60 * SECONDS
```
Quantities are then created with the '@' operator, using a numeric value and the desired
unit, for example 3m:
```python
from kodo.quantities import Quantity
distance: Quantity[Distance] = 3 @ Distance.METERS
```
Quantities can be compared with, added to, and subtracted from other quantities of the same
type. Note that while use of different types of quantities together will not be caught at
run time, a type checker will report it as an error. The following examples use quantities
of the `Distance` type, so all work:
```python
assert (3 @ Distance.METERS) == (300 @ Distance.CENTIMETERS) == (3000 @ Distance.MILLIMETERS)
assert (3 @ Distance.METERS) + (2.5 @ Distance.METERS) == (5.5 @ Distance.METERS)
```
Scaling with multiplication and division must be with unitless values:
```python
assert (3 @ Distance.METERS) * 2.0 == (6 @ Distance.METERS)
assert (3 @ Distance.METERS) / 2 == (1.5 @ Distance.METERS)
```
Division with the floor division operator '//' and finding the remainder with the modulus
operator '%' work a little differently; the second argument must be another quantity:
```python
# 10m divides into 3m three times…
assert (10 @ Distance.METERS) // (3 @ Distance.METERS) == 3
# … with 1m left over
assert (10 @ Distance.METERS) % (3 @ Distance.METERS) == (1 @ Distance.METERS)
```
Finally, for most uses the quantity will eventually have to be converted back to a unitless
value of a known fixed unit, for example to pass to an external API, or store in a database.
This is done with the right shift operator '>>':
```python
import time
def get_delay() -> Quantity[Time]:
return 10000 @ Time.MILLISECONDS
# time.sleep() takes a single float argument for the sleep time in seconds
time.sleep( get_delay() >> Time.SECONDS )
```
If for some reason an integer value is needed instead, the floor division operator can be
used as described above with a value of 1 of the desired unit. As a convenience the unit
item itself can be used, matching the '>>' operator:
```python
assert (3.6 @ Time.SECONDS) // (1 @ Time.SECONDS) is 3
assert (3.6 @ Time.SECONDS) // Time.SECONDS is 3
```