|
| 1 | +Metadata-Version: 2.1 |
| 2 | +Name: unit-system-py |
| 3 | +Version: 0.8.0rc5 |
| 4 | +Summary: A simple unit system for python |
| 5 | +Author-email: noasakurajin < [email protected]> |
| 6 | +Project-URL: Homepage, https://github.com/noah1510/unit-system-generator |
| 7 | +Project-URL: Bug Tracker, https://github.com/noah1510/unit-system-generator/issues |
| 8 | +Classifier: Programming Language :: Python :: 3 |
| 9 | +Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3) |
| 10 | +Classifier: Operating System :: OS Independent |
| 11 | +Classifier: Topic :: Scientific/Engineering :: Physics |
| 12 | +Classifier: Typing :: Typed |
| 13 | +Requires-Python: >=3.8 |
| 14 | +Description-Content-Type: text/markdown |
| 15 | +License-File: LICENSE |
| 16 | + |
| 17 | +# unit-system Python |
| 18 | + |
| 19 | +**As of version 0.6.0 all the source code is generated by python scripts.** |
| 20 | +**This repository only contains the generated source files.** |
| 21 | +**If you want to report a bug or change something check the [generator repository](https:://github.com/noah1510/unit-system-generator).** |
| 22 | + |
| 23 | + |
| 24 | +This is an implementation of the SI unit system for Python development. |
| 25 | +All units, combinations, literals and constants are generated from templates. |
| 26 | +If you feel something is missing open an issue or a pull request on the [generator repository](https:://github.com/noah1510/unit-system-generator). |
| 27 | + |
| 28 | +## Usage examples |
| 29 | + |
| 30 | +```python |
| 31 | +from unit_system_py import literals |
| 32 | + |
| 33 | +# create some units |
| 34 | +l1 = literals.km(10) |
| 35 | +t1 = literals.s(5) |
| 36 | + |
| 37 | +# combine the two units to the correct one |
| 38 | +v1 = l1 / t1 |
| 39 | + |
| 40 | +# print the result, with correct unit names |
| 41 | +# This should print |
| 42 | +# 10000 meter in 5 second is 2000 meter / second |
| 43 | +print(l1, "in", t1, "is", v1) |
| 44 | + |
| 45 | +``` |
| 46 | + |
| 47 | +As you can see using the unit system is pretty easy. |
| 48 | +The literals class contains all implemented SI unit names. |
| 49 | +You can use them to create units with the correct multiplier and offset. |
| 50 | + |
| 51 | +While it is generally better to create units using the literals, it is also possible to include the units directly. |
| 52 | +Just note that you have to manually set the multiplier, since the unit is not created using the literals. |
| 53 | + |
| 54 | +```python |
| 55 | +from unit_system_py import time, length |
| 56 | + |
| 57 | +# create some units |
| 58 | +l1 = length(10, 1000) |
| 59 | +t1 = time(5) |
| 60 | + |
| 61 | +# combine the two units to the correct one |
| 62 | +v1 = l1 / t1 |
| 63 | + |
| 64 | +# print the result, with correct unit names |
| 65 | +# This should print |
| 66 | +# 10000 meter in 5 second is 2000 meter / second |
| 67 | +print(l1, "in", t1, "is", v1) |
| 68 | +``` |
| 69 | + |
| 70 | +This allows to specify multipliers that are not created by the literals. |
| 71 | +Another use of this, is to specify type hints for the units. |
| 72 | +This is highly encouraged, when defining functions that take units as arguments. |
| 73 | + |
| 74 | +```python |
| 75 | +from unit_system_py import length, speed, literals |
| 76 | +from math import sin, radians |
| 77 | + |
| 78 | +# create an example function which calculates a throw distance from a speed and angle |
| 79 | +def throw_distance(throw_speed: speed, angle_degrees: float) -> length: |
| 80 | + # verify that the correct unit is passed |
| 81 | + if not isinstance(throw_speed, speed): |
| 82 | + raise TypeError("throw_speed must be of type speed") |
| 83 | + |
| 84 | + # convert the angle to radians |
| 85 | + angle = radians(angle_degrees) |
| 86 | + # get the speed in m/s and the local gravity acceleration |
| 87 | + speed_mps = float(throw_speed) |
| 88 | + g = float(literals.G(1)) |
| 89 | + # calculate the distance |
| 90 | + return speed_mps**2 * sin(2 * angle) / g |
| 91 | + |
| 92 | +# get the distance for a throw with 10 m/s and 45 degrees |
| 93 | +print(throw_distance(literals.mps(10), 45)) |
| 94 | +``` |
| 95 | + |
| 96 | +Because not all combinations of units are implemented, you can also cast units to a float. |
| 97 | +Calling float on a unit will return the value of the unit in the base unit. |
| 98 | +Alternatively you can also use the `convert_to` method to convert a unit to another multiplier and offset. |
| 99 | +If you want to use the `value` property directly, make sure to check the multiplier and offset first. |
| 100 | +If you don't do this, you might get wrong results since the value of `literals.km(1)` is the same as the value of `literals.m(1)`. |
| 101 | +They have to be converted to the same multiplier and offset before you can use them directly. |
| 102 | +All functions of the unit_system either do this, or they also combine the multipliers and offsets correctly. |
| 103 | + |
| 104 | +## Units that are currently supported |
| 105 | + |
| 106 | +* time -> time with seconds as base unit |
| 107 | +* length -> length with meter as base unit |
| 108 | +* mass -> mass with kg as base unit |
| 109 | +* temperature -> temperature with K as base unit |
| 110 | +* amount -> amount of substance with mole as base unit |
| 111 | +* electric_current -> electric current with Ampere as base unit |
| 112 | +* luminous_intensity -> luminous intensity with candela as base unit |
| 113 | +* area -> area with `m^2` as base unit |
| 114 | +* speed -> speed with `m / s` as base unit |
| 115 | +* acceleration -> acceleration with `m / s^2` as base unit |
| 116 | +* momentum -> momentum with `kg * m / s` as base unit |
| 117 | +* force -> force with `kg * m / s^2` (Newton) as base unit |
| 118 | +* energy -> energy with `kg * m^2 / s^2` (Joules) as base unit |
| 119 | +* power -> power with `kg * m^2 / s^3` (Watts) as base unit |
| 120 | + |
| 121 | +## Upgrade Instructions |
| 122 | + |
| 123 | +Since 0.8.0 is the first release, there are no upgrade instructions yet. |
0 commit comments