# UnitPy (Unit Python)
---
---
UnitPy is a Python package for defining, converting, and working with units.
The goal of the package is to be simple, straightforward, and performant.
This package directly implements [NIST (National Institute of Standards and Technology)](https://www.nist.gov/pml/special-publication-811/nist-guide-si-chapter-1-introduction)
official unit definitions.
---
## Installation
Pip installable package:
`pip install unitpy`
[pypi: unitpy](https://pypi.org/project/unitpy/)
---
## Requirements / Dependencies
Python 3.8 and up
---
## Basic Usage
### Defining Unit
```python
from unitpy import U, Q, Unit, Quantity
# U = Unit
u = Unit("kilometer")
u = U("kilometer")
u = U("km")
u = U.kilometer
u = U.km
u = U("kilometer/hour")
u = U("km/h")
u = U.kilometer / U.hour
u = U.km / U.h
# properties
print(u.dimensionality) # [length] / [time]
print(u.dimensionless) # False
print(u.base_unit) # meter / second
```
### Defining Quantity
** Quantity = Value + Unit **
```python
from unitpy import U, Q , Unit, Quantity
# Q = Quantity
q = 1 * U("kilometer/hour")
q = 1 * (U.kilometer / U.hour)
q = Quantity("1 km/h")
q = Q("1 kilometer per hour")
q = Q("1*kilometer/hour")
# properties
print(q.unit) # kilometer / hour
print(q.dimensionality) # [length] / [time]
print(q.dimensionless) # False
print(q.base_unit) # meter / second
```
### Unit Conversion
```python
from unitpy import U, Q , Unit, Quantity
# Q = Quantity
q = 1 * U("km/h")
q2 = q.to("mile per hour")
print(q2) # 0.6213711922 mile / hour
```
### Mathematical operation
```python
from unitpy import U, Q
q = 1 * U("km/h")
q2 = 2.2 * U("mile per hour")
print(q2 + q) # 2.8213711923 mile / hour
print(q2 - q) # 1.5786288077 mile / hour
print(q2 * q) # 2.2 kilometer mile / hour**2
print(q2 / q) # 2.2 mile / kilometer
print((q2 / q).dimensionless) # True
```
Other supported functions:
* `sum`
* `max`
* `min`
### Temperature
__Abbreviations:__
* fahrenheits: degF
* celsius: degC
* kelvin: degK, K
* rankine: degR
```python
from unitpy import U, Q
q = 300 * U("K")
q2 = 200 * U("K")
print(q + q2) # 500.0 kelvin
print(q.to("degC")) # 26.85 Celsius
print(q.to("degF")) # 830.6344444444 Fahrenheit
print(q.to("degR")) # 166.6666666667 Rankine
```
Temperature units are non-multiplicative units. They are expressed with respect to a reference point (offset).
> degC = 5/9 * (degF - 32)
Default behavior is **absolute units**.
For **relative units** use dedicated functions `add_rel()` or `sub_rel()`.
```python
from unitpy import U, Q
q = 10 * U("degC")
q2 = 5 * U("degC")
# absolute
print(q.to("K")) # 283.15 kelvin
print(q + q2) # 288.15 Celsius
print((q + q2).to("K")) # 561.3 kelvin
print(q - q2) # -268.15 Celsius
print((q - q2).to("K")) # 5.0 kelvin
# relative
print(q.add_rel(q2)) # 15 Celsius
print(q.sub_rel(q2)) # 5 Celsius
print(abs(-10 * U.degC)) # 10 Celsius
```
### Time
```python
from datetime import timedelta
from unitpy import U
a = 1.234 * U.min
print(a) # 1.234 minute
b = a.to_timedelta()
print(b) # 0:01:14.040000
print(type(b)) # <class 'datetime.timedelta'>
```
### string formatting
```python
from unitpy import U
a = 1.23432453 * U.min
print(a) # 1.23432453 minute
print(f"{a:.2f}") # 1.23 minute
b = 1_000_000 * U.cm
print(b) # 1000000 centimeter
print(format(b, ",")) # 1,000,000 centimeter
c = 123 * U.inch
print(c) # 123 inch
print(f"{c:5}") # 123 inch (leading spaces)
print(f"{c:05}") # 00123 inch (leading zeros)
```
#### configuration with .env
To configure the string outputs with environment file (.env):
1) install [python-dotenv](https://github.com/theskumar/python-dotenv/tree/main). The code uses this to load
variables from the .env file
```commandline
pip install python-dotenv
```
2) copy the .env file from this repo into the top level of your repo and edit to your liking
It should now load the environmental variables when you run the code to format it to your liking without any
additional code needed.
## Numpy Support
[Numpy](https://github.com/numpy/numpy)
```python
import numpy as np
from unitpy import Unit, Quantity
# numpy + int
a = np.linspace(0, 4, 5) * Unit.m
b = 1 * Unit.ft
c = a+b
print(a+b) # [0.3048 1.3048 2.3048 3.3048 4.3048] meter
print(a-b) # [-0.3048 0.6952 1.6952 2.6952 3.6952] meter
a += b
print(a) # [0.3048 1.3048 2.3048 3.3048 4.3048] meter
# numpy + numpy
a = np.linspace(0, 4, 5) * Unit.m
b = np.linspace(0, 4, 5) * Unit.ft
print(a+b) # [0. 1.3048 2.6096 3.9144 5.2192] meter
print(a-b) # [0. 0.6952 1.3904 2.0856 2.7808] meter
a += b
print(a) # [0. 1.3048 2.6096 3.9144 5.2192] meter
# numpy * int
a = np.linspace(0, 4, 5) * Unit.m
b = 1.2 * Unit.s
print(a*b) # [0. 1.2 2.4 3.6 4.8] meter second
print(a/b) # [0. 0.83333333 1.66666667 2.5 3.33333333] meter/second
a *= b
print(a) # [0. 1.2 2.4 3.6 4.8] meter second
# numpy * numpy
a = np.linspace(0, 4, 5) * Unit.m
b = np.linspace(0, 4, 5) * Unit.s
print(a*b) # [ 0. 1. 4. 9. 16.] meter second
print(a/b) # [nan 1. 1. 1. 1.] meter/second
a *= b
print(a) # [ 0. 1. 4. 9. 16.] meter second
# numpy functions
a = np.linspace(-2, 4, 5) * Unit.m
print(np.sum(a)) # 5 meter
print(np.max(a)) # 4 meter
print(np.abs(a)) # [2. 0.5 1. 2.5 4. ] meter
print(np.linspace(1*Unit.mm, 2*Unit.ft, 4)) # [ 1. 203.86666667 406.73333333 609.6 ] millimeter
```
---
## Notes
* this package utilizes the American spellings "meter," "liter," and "ton"
* supports pickling
Raw data
{
"_id": null,
"home_page": "https://github.com/dylanwal/unitpy",
"name": "unitpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Dylan Walsh",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ea/0c/c7764d46b77c6f4af8722506b80d5210aaa850a68a837a48d8c62a879698/unitpy-0.0.18.tar.gz",
"platform": "any",
"description": "# UnitPy (Unit Python)\r\n\r\n---\r\n---\r\n\r\n\r\n\r\n\r\n\r\n\r\nUnitPy is a Python package for defining, converting, and working with units. \r\n\r\nThe goal of the package is to be simple, straightforward, and performant. \r\n\r\nThis package directly implements [NIST (National Institute of Standards and Technology)](https://www.nist.gov/pml/special-publication-811/nist-guide-si-chapter-1-introduction) \r\nofficial unit definitions. \r\n\r\n---\r\n\r\n## Installation\r\n\r\nPip installable package:\r\n\r\n`pip install unitpy`\r\n\r\n[pypi: unitpy](https://pypi.org/project/unitpy/)\r\n\r\n\r\n---\r\n\r\n## Requirements / Dependencies\r\n\r\nPython 3.8 and up\r\n\r\n---\r\n\r\n## Basic Usage\r\n\r\n### Defining Unit\r\n\r\n```python\r\nfrom unitpy import U, Q, Unit, Quantity\r\n# U = Unit\r\n\r\nu = Unit(\"kilometer\")\r\nu = U(\"kilometer\")\r\nu = U(\"km\")\r\nu = U.kilometer\r\nu = U.km\r\n\r\nu = U(\"kilometer/hour\")\r\nu = U(\"km/h\")\r\nu = U.kilometer / U.hour\r\nu = U.km / U.h\r\n\r\n# properties\r\nprint(u.dimensionality) # [length] / [time]\r\nprint(u.dimensionless) # False\r\nprint(u.base_unit) # meter / second\r\n```\r\n\r\n\r\n### Defining Quantity\r\n\r\n** Quantity = Value + Unit **\r\n\r\n```python\r\nfrom unitpy import U, Q , Unit, Quantity\r\n# Q = Quantity\r\n\r\nq = 1 * U(\"kilometer/hour\") \r\nq = 1 * (U.kilometer / U.hour)\r\nq = Quantity(\"1 km/h\")\r\nq = Q(\"1 kilometer per hour\")\r\nq = Q(\"1*kilometer/hour\")\r\n\r\n\r\n# properties\r\nprint(q.unit) # kilometer / hour\r\nprint(q.dimensionality) # [length] / [time]\r\nprint(q.dimensionless) # False\r\nprint(q.base_unit) # meter / second\r\n```\r\n\r\n\r\n### Unit Conversion\r\n\r\n```python\r\nfrom unitpy import U, Q , Unit, Quantity\r\n# Q = Quantity\r\n\r\nq = 1 * U(\"km/h\") \r\nq2 = q.to(\"mile per hour\")\r\nprint(q2) # 0.6213711922 mile / hour\r\n```\r\n\r\n\r\n### Mathematical operation\r\n\r\n```python\r\nfrom unitpy import U, Q \r\n\r\nq = 1 * U(\"km/h\") \r\nq2 = 2.2 * U(\"mile per hour\")\r\nprint(q2 + q) # 2.8213711923 mile / hour\r\nprint(q2 - q) # 1.5786288077 mile / hour\r\nprint(q2 * q) # 2.2 kilometer mile / hour**2\r\nprint(q2 / q) # 2.2 mile / kilometer\r\nprint((q2 / q).dimensionless) # True\r\n```\r\n\r\nOther supported functions:\r\n* `sum`\r\n* `max`\r\n* `min`\r\n\r\n### Temperature\r\n\r\n__Abbreviations:__\r\n\r\n* fahrenheits: degF\r\n* celsius: degC\r\n* kelvin: degK, K\r\n* rankine: degR\r\n\r\n```python\r\nfrom unitpy import U, Q\r\n\r\nq = 300 * U(\"K\")\r\nq2 = 200 * U(\"K\")\r\n\r\nprint(q + q2) # 500.0 kelvin\r\nprint(q.to(\"degC\")) # 26.85 Celsius\r\nprint(q.to(\"degF\")) # 830.6344444444 Fahrenheit\r\nprint(q.to(\"degR\")) # 166.6666666667 Rankine\r\n```\r\n\r\nTemperature units are non-multiplicative units. They are expressed with respect to a reference point (offset).\r\n> degC = 5/9 * (degF - 32) \r\n\r\nDefault behavior is **absolute units**.\r\n\r\nFor **relative units** use dedicated functions `add_rel()` or `sub_rel()`.\r\n\r\n```python\r\nfrom unitpy import U, Q\r\n\r\nq = 10 * U(\"degC\")\r\nq2 = 5 * U(\"degC\")\r\n\r\n# absolute\r\nprint(q.to(\"K\")) # 283.15 kelvin\r\nprint(q + q2) # 288.15 Celsius \r\nprint((q + q2).to(\"K\")) # 561.3 kelvin\r\nprint(q - q2) # -268.15 Celsius\r\nprint((q - q2).to(\"K\")) # 5.0 kelvin\r\n\r\n# relative\r\nprint(q.add_rel(q2)) # 15 Celsius\r\nprint(q.sub_rel(q2)) # 5 Celsius\r\nprint(abs(-10 * U.degC)) # 10 Celsius\r\n```\r\n\r\n\r\n### Time\r\n\r\n```python\r\nfrom datetime import timedelta\r\nfrom unitpy import U\r\n\r\na = 1.234 * U.min\r\nprint(a) # 1.234 minute\r\nb = a.to_timedelta()\r\nprint(b) # 0:01:14.040000\r\nprint(type(b)) # <class 'datetime.timedelta'>\r\n```\r\n\r\n\r\n### string formatting\r\n\r\n```python\r\nfrom unitpy import U\r\n\r\na = 1.23432453 * U.min\r\nprint(a) # 1.23432453 minute\r\nprint(f\"{a:.2f}\") # 1.23 minute\r\nb = 1_000_000 * U.cm\r\nprint(b) # 1000000 centimeter\r\nprint(format(b, \",\")) # 1,000,000 centimeter\r\nc = 123 * U.inch\r\nprint(c) # 123 inch\r\nprint(f\"{c:5}\") # 123 inch (leading spaces)\r\nprint(f\"{c:05}\") # 00123 inch (leading zeros)\r\n```\r\n\r\n#### configuration with .env\r\n\r\nTo configure the string outputs with environment file (.env):\r\n\r\n1) install [python-dotenv](https://github.com/theskumar/python-dotenv/tree/main). The code uses this to load \r\n variables from the .env file\r\n```commandline\r\npip install python-dotenv\r\n```\r\n\r\n2) copy the .env file from this repo into the top level of your repo and edit to your liking\r\n\r\nIt should now load the environmental variables when you run the code to format it to your liking without any \r\nadditional code needed.\r\n\r\n\r\n## Numpy Support\r\n\r\n[Numpy](https://github.com/numpy/numpy)\r\n\r\n```python\r\nimport numpy as np\r\n\r\nfrom unitpy import Unit, Quantity\r\n\r\n# numpy + int\r\na = np.linspace(0, 4, 5) * Unit.m\r\nb = 1 * Unit.ft\r\nc = a+b\r\nprint(a+b) # [0.3048 1.3048 2.3048 3.3048 4.3048] meter\r\nprint(a-b) # [-0.3048 0.6952 1.6952 2.6952 3.6952] meter\r\na += b\r\nprint(a) # [0.3048 1.3048 2.3048 3.3048 4.3048] meter\r\n\r\n# numpy + numpy\r\na = np.linspace(0, 4, 5) * Unit.m\r\nb = np.linspace(0, 4, 5) * Unit.ft\r\nprint(a+b) # [0. 1.3048 2.6096 3.9144 5.2192] meter\r\nprint(a-b) # [0. 0.6952 1.3904 2.0856 2.7808] meter\r\na += b\r\nprint(a) # [0. 1.3048 2.6096 3.9144 5.2192] meter\r\n\r\n# numpy * int\r\na = np.linspace(0, 4, 5) * Unit.m\r\nb = 1.2 * Unit.s\r\nprint(a*b) # [0. 1.2 2.4 3.6 4.8] meter second\r\nprint(a/b) # [0. 0.83333333 1.66666667 2.5 3.33333333] meter/second\r\na *= b\r\nprint(a) # [0. 1.2 2.4 3.6 4.8] meter second\r\n\r\n# numpy * numpy\r\na = np.linspace(0, 4, 5) * Unit.m\r\nb = np.linspace(0, 4, 5) * Unit.s\r\nprint(a*b) # [ 0. 1. 4. 9. 16.] meter second\r\nprint(a/b) # [nan 1. 1. 1. 1.] meter/second\r\na *= b\r\nprint(a) # [ 0. 1. 4. 9. 16.] meter second\r\n\r\n\r\n# numpy functions\r\na = np.linspace(-2, 4, 5) * Unit.m\r\nprint(np.sum(a)) # 5 meter\r\nprint(np.max(a)) # 4 meter\r\nprint(np.abs(a)) # [2. 0.5 1. 2.5 4. ] meter\r\nprint(np.linspace(1*Unit.mm, 2*Unit.ft, 4)) # [ 1. 203.86666667 406.73333333 609.6 ] millimeter\r\n```\r\n\r\n---\r\n\r\n## Notes\r\n\r\n* this package utilizes the American spellings \"meter,\" \"liter,\" and \"ton\"\r\n* supports pickling \r\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Working with scientific units in python.",
"version": "0.0.18",
"project_urls": {
"Homepage": "https://github.com/dylanwal/unitpy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7eaf1a2e2b9bf823021ba79a0125f601a8f742a84085358ed7e8599b2660d9ca",
"md5": "cc6979fd1cb20059f03761dff759988b",
"sha256": "ce9b280ac3d7e611e98f5f75c29e6814e5bb988c944d6ce09ef36cb502cb2610"
},
"downloads": -1,
"filename": "unitpy-0.0.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc6979fd1cb20059f03761dff759988b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 33375,
"upload_time": "2024-09-02T17:14:56",
"upload_time_iso_8601": "2024-09-02T17:14:56.938985Z",
"url": "https://files.pythonhosted.org/packages/7e/af/1a2e2b9bf823021ba79a0125f601a8f742a84085358ed7e8599b2660d9ca/unitpy-0.0.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea0cc7764d46b77c6f4af8722506b80d5210aaa850a68a837a48d8c62a879698",
"md5": "2492a4a5ca7081a9dcef052811dd9eeb",
"sha256": "024e029e63f749a2e6f0cfc2a5617bb668ea2b7b3ad0da13b1ab87b13195f107"
},
"downloads": -1,
"filename": "unitpy-0.0.18.tar.gz",
"has_sig": false,
"md5_digest": "2492a4a5ca7081a9dcef052811dd9eeb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 34868,
"upload_time": "2024-09-02T17:14:58",
"upload_time_iso_8601": "2024-09-02T17:14:58.740028Z",
"url": "https://files.pythonhosted.org/packages/ea/0c/c7764d46b77c6f4af8722506b80d5210aaa850a68a837a48d8c62a879698/unitpy-0.0.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 17:14:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dylanwal",
"github_project": "unitpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "unitpy"
}
JSON
