# unitsnet-py
[](https://github.com/haimkastner/unitsnet-py/actions)
[](https://github.com/haimkastner/unitsnet-py/releases)
[](https://pypi.org/project/unitsnet-py/)
[](https://github.com/haimkastner/unitsnet-py/stargazers)
[](https://pypi.org/project/unitsnet-py/)
[](https://github.com/haimkastner/unitsnet-py/blob/master/LICENSE)
The unitsnet-py package provides an efficient way to store unit variables and perform easy conversions to different units when it required.
It offers support for more than 100 unit types across various unit categories, including pretty-printing, comparison, and arithmetic methods.
The API is designed to be user-friendly and straightforward to use.
The library is built on top of the [Units.NET](https://github.com/angularsen/UnitsNet) project and leverages their [definitions sources](https://github.com/angularsen/UnitsNet/tree/master/Common/UnitDefinitions) to generate the Python unit classes.
###### The unitsnet-py package does not require any external dependencies or packages to function.
Package is available on PyPI at https://pypi.org/project/unitsnet-py/
[Units.NET on other platforms](#unitsnet-on-other-platforms)
## Install via PyPi
```bash
pip install unitsnet-py
```
## Example Usage
```python
from unitsnet_py import Angle, AngleUnits, Length, LengthUnits
angle = Angle.from_degrees(180)
# equals to
angle = Angle(180, AngleUnits.Degree)
print(angle.radians) # 3.141592653589793
print(angle.microradians) # 3141592.65358979
print(angle.gradians) # 200
print(angle.microdegrees) # 180000000
# As an alternative, a convert style method are also available
print(angle.convert(AngleUnits.Radian)) # 3.141592653589793
print(angle.convert(AngleUnits.Microradian)) # 3141592.65358979
print(angle.convert(AngleUnits.Gradian)) # 200
print(angle.convert(AngleUnits.Microdegree)) # 180000000
# Print the default unit to_string (The default for angle is degrees)
print(angle.to_string()) # 180 °
print(angle.to_string(AngleUnits.Degree)) # 180 °
print(angle.to_string(AngleUnits.Radian)) # 3.141592653589793 rad
# Specify fraction digits max length
print(angle.to_string(AngleUnits.Radian, 2)) # 3.14 rad
```
## Additional methods
Check, compare, calculate etc. with unitsnet:
```python
length1 = Length.from_meters(10)
length2 = Length.from_decimeters(100)
length3 = Length.from_meters(3)
# 'equals' method
print(length1 == length2) # True
print(length1 == length3) # False
# 'compareTo' method
print(length3 > length1) # False
print(length3 < length1) # True
print(length2 >= length1) # True
# Arithmetics methods
results1 = length1 + length3
results2 = length1 - length3
results3 = length1 * length3
results4 = length1 / length3
results5 = length1 % length3
results6 = length1 ** length3
print(results1.to_string(LengthUnits.Meter)) # 13 m
print(results2.to_string(LengthUnits.Meter)) # 7 m
print(results3.to_string(LengthUnits.Meter)) # 30 m
print(results4.to_string(LengthUnits.Meter)) # 3.3333333333333335 m
print(results5.to_string(LengthUnits.Meter)) # 1 m
print(results6.to_string(LengthUnits.Meter)) # 1000 m
# Complex objects
# Any object supports arithmetic operations can be used as well as unit
# see numpy array example:
import numpy as np
np_array = np.array([[2, 4, 6], [7, 8, 9]])
np_array_length = Length.from_kilometers(np_array)
print(np_array_length.meters) # [[2000. 4000. 6000.][7000. 8000. 9000.]]
np_array_double_length = np_array_length + np_array_length
print(np_array_double_length.kilometers) # [[ 4. 8. 12.][14. 16. 18.]]
print(np_array_double_length.meters) # [[ 4000. 8000. 12000.][14000. 16000. 18000.]]
```
## DTO - Data Transfer Object
As UnitsNet provides a convenient way to work within a running service, there are occasions where the data needs to be exposed outside of the service, typically through an API containing the unit value or consumed from an API.
To support this with a clear API schema and make it easy to convert to and from this schema to the specific format, it's recommended to use DTOs and the UnitsNet flavor converters.
```python
from unitsnet_py import Length, LengthDto, LengthUnits
# Create a Length unit object
length = Length.from_meters(100.01)
# Obtain the DTO object as json, represented by the default unit - meter
length_dto_json = length.to_dto_json() # {"value":100.01,"unit":"Meter"}
# Obtain the same value but represent DTO in KM
length_dto_represents_in_km_json = length.to_dto_json(LengthUnits.Kilometer) # {'value': 0.10001, 'unit': 'Kilometer'}
# Load JSON to DTO, and load
length_from_meters_dto = Length.from_dto_json(length_dto_json)
# The exact same value as
length_from_km_dto = Length.from_dto_json(length_dto_represents_in_km_json)
# Additionally, it supports creating and handling as a DTO instance, as well as creating and converting to/from JSON.
# Get a DTO instance from a Length instance
length_dto: LengthDto = length.to_dto()
# Get the json representation of the DTO
length_json = length_dto.to_json() # {"value":100.01,"unit":"Meter"}
# Obtain DTO instance from a json representation
length_dto: LengthDto = LengthDto.from_json(length_json)
# Obtain Length unit from a DTO instance
length = Length.from_dto(length_dto)
```
Check out the OpenAPI [unitsnet-openapi-spec](https://haimkastner.github.io/unitsnet-openapi-spec-example/) example schema.
Also, refer to the detailed discussions on GitHub: [haimkastner/unitsnet-js#31](https://github.com/haimkastner/unitsnet-js/issues/31) & [angularsen/UnitsNet#1378](https://github.com/angularsen/UnitsNet/issues/1378).
## Supported units
[UnitsNet supported Units](https://github.com/haimkastner/unitsnet-py/blob/main/Units.md)
## Units.NET on other platforms
Get the same strongly typed units on other platforms, based on the same [unit definitions](/Common/UnitDefinitions).
| Language | Name | Package | Repository | Maintainers |
|----------------------------|-------------|---------------------------------------------------------------------|------------------------------------------------------|--------------|
| C# | UnitsNet | [nuget](https://www.nuget.org/packages/UnitsNet/) | [github](https://github.com/angularsen/UnitsNet) | @angularsen |
| JavaScript /<br>TypeScript | unitsnet-js | [npm](https://www.npmjs.com/package/unitsnet-js) | [github](https://github.com/haimkastner/unitsnet-js) | @haimkastner |
| Python | unitsnet-py | [pypi](https://pypi.org/project/unitsnet-py) | [github](https://github.com/haimkastner/unitsnet-py) | @haimkastner |
| Golang | unitsnet-go | [pkg.go.dev](https://pkg.go.dev/github.com/haimkastner/unitsnet-go) | [github](https://github.com/haimkastner/unitsnet-go) | @haimkastner |
Raw data
{
"_id": null,
"home_page": "https://github.com/haimkastner/unitsnet-py",
"name": "unitsnet-py",
"maintainer": "Haim Kastner",
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": "hello@haim-kastner.com",
"keywords": "conversion, units-of-measure, units, quantities, unit-converter, converter, unit, measure, measures, measurement, measurements",
"author": "Haim Kastner",
"author_email": "hello@haim-kastner.com",
"download_url": "https://files.pythonhosted.org/packages/d5/ac/4bc413925d2ec32324dae7d678a6dc4810aac67bda0d476e19f4a1445880/unitsnet-py-0.1.135.tar.gz",
"platform": null,
"description": "# unitsnet-py\n\n[](https://github.com/haimkastner/unitsnet-py/actions)\n\n [](https://github.com/haimkastner/unitsnet-py/releases) \n[](https://pypi.org/project/unitsnet-py/)\n\n\n[](https://github.com/haimkastner/unitsnet-py/stargazers) \n[](https://pypi.org/project/unitsnet-py/)\n[](https://github.com/haimkastner/unitsnet-py/blob/master/LICENSE)\n\nThe unitsnet-py package provides an efficient way to store unit variables and perform easy conversions to different units when it required. \n\nIt offers support for more than 100 unit types across various unit categories, including pretty-printing, comparison, and arithmetic methods. \n\nThe API is designed to be user-friendly and straightforward to use.\n\nThe library is built on top of the [Units.NET](https://github.com/angularsen/UnitsNet) project and leverages their [definitions sources](https://github.com/angularsen/UnitsNet/tree/master/Common/UnitDefinitions) to generate the Python unit classes.\n\n###### The unitsnet-py package does not require any external dependencies or packages to function.\n\n\nPackage is available on PyPI at https://pypi.org/project/unitsnet-py/\n\n[Units.NET on other platforms](#unitsnet-on-other-platforms)\n\n## Install via PyPi\n\n```bash \npip install unitsnet-py\n```\n\n## Example Usage\n\n```python\nfrom unitsnet_py import Angle, AngleUnits, Length, LengthUnits\n\n\nangle = Angle.from_degrees(180)\n# equals to\nangle = Angle(180, AngleUnits.Degree)\n\nprint(angle.radians) # 3.141592653589793\nprint(angle.microradians) # 3141592.65358979\nprint(angle.gradians) # 200\nprint(angle.microdegrees) # 180000000\n\n\n# As an alternative, a convert style method are also available\nprint(angle.convert(AngleUnits.Radian)) # 3.141592653589793\nprint(angle.convert(AngleUnits.Microradian)) # 3141592.65358979\nprint(angle.convert(AngleUnits.Gradian)) # 200\nprint(angle.convert(AngleUnits.Microdegree)) # 180000000\n\n\n# Print the default unit to_string (The default for angle is degrees)\nprint(angle.to_string()) # 180 \u00b0\n\nprint(angle.to_string(AngleUnits.Degree)) # 180 \u00b0\nprint(angle.to_string(AngleUnits.Radian)) # 3.141592653589793 rad\n\n# Specify fraction digits max length\nprint(angle.to_string(AngleUnits.Radian, 2)) # 3.14 rad\n```\n\n## Additional methods\n\nCheck, compare, calculate etc. with unitsnet:\n\n```python\nlength1 = Length.from_meters(10)\nlength2 = Length.from_decimeters(100)\nlength3 = Length.from_meters(3)\n\n# 'equals' method\nprint(length1 == length2) # True\nprint(length1 == length3) # False\n\n# 'compareTo' method\nprint(length3 > length1) # False\nprint(length3 < length1) # True\nprint(length2 >= length1) # True\n\n# Arithmetics methods\nresults1 = length1 + length3\nresults2 = length1 - length3\nresults3 = length1 * length3\nresults4 = length1 / length3\nresults5 = length1 % length3\nresults6 = length1 ** length3\nprint(results1.to_string(LengthUnits.Meter)) # 13 m\nprint(results2.to_string(LengthUnits.Meter)) # 7 m\nprint(results3.to_string(LengthUnits.Meter)) # 30 m\nprint(results4.to_string(LengthUnits.Meter)) # 3.3333333333333335 m\nprint(results5.to_string(LengthUnits.Meter)) # 1 m\nprint(results6.to_string(LengthUnits.Meter)) # 1000 m\n\n# Complex objects\n\n# Any object supports arithmetic operations can be used as well as unit\n# see numpy array example:\nimport numpy as np\n\nnp_array = np.array([[2, 4, 6], [7, 8, 9]])\n\nnp_array_length = Length.from_kilometers(np_array)\nprint(np_array_length.meters) # [[2000. 4000. 6000.][7000. 8000. 9000.]]\n\nnp_array_double_length = np_array_length + np_array_length\nprint(np_array_double_length.kilometers) # [[ 4. 8. 12.][14. 16. 18.]]\nprint(np_array_double_length.meters) # [[ 4000. 8000. 12000.][14000. 16000. 18000.]]\n\n```\n## DTO - Data Transfer Object\n\nAs UnitsNet provides a convenient way to work within a running service, there are occasions where the data needs to be exposed outside of the service, typically through an API containing the unit value or consumed from an API.\n\nTo support this with a clear API schema and make it easy to convert to and from this schema to the specific format, it's recommended to use DTOs and the UnitsNet flavor converters.\n\n```python\nfrom unitsnet_py import Length, LengthDto, LengthUnits\n\n # Create a Length unit object\nlength = Length.from_meters(100.01)\n# Obtain the DTO object as json, represented by the default unit - meter\nlength_dto_json = length.to_dto_json() # {\"value\":100.01,\"unit\":\"Meter\"}\n# Obtain the same value but represent DTO in KM \nlength_dto_represents_in_km_json = length.to_dto_json(LengthUnits.Kilometer) # {'value': 0.10001, 'unit': 'Kilometer'}\n# Load JSON to DTO, and load\nlength_from_meters_dto = Length.from_dto_json(length_dto_json)\n# The exact same value as\nlength_from_km_dto = Length.from_dto_json(length_dto_represents_in_km_json)\n\n# Additionally, it supports creating and handling as a DTO instance, as well as creating and converting to/from JSON.\n\n# Get a DTO instance from a Length instance\nlength_dto: LengthDto = length.to_dto()\n# Get the json representation of the DTO\nlength_json = length_dto.to_json() # {\"value\":100.01,\"unit\":\"Meter\"}\n# Obtain DTO instance from a json representation\nlength_dto: LengthDto = LengthDto.from_json(length_json)\n# Obtain Length unit from a DTO instance\nlength = Length.from_dto(length_dto)\n```\n\nCheck out the OpenAPI [unitsnet-openapi-spec](https://haimkastner.github.io/unitsnet-openapi-spec-example/) example schema.\n\nAlso, refer to the detailed discussions on GitHub: [haimkastner/unitsnet-js#31](https://github.com/haimkastner/unitsnet-js/issues/31) & [angularsen/UnitsNet#1378](https://github.com/angularsen/UnitsNet/issues/1378).\n\n## Supported units\n\n[UnitsNet supported Units](https://github.com/haimkastner/unitsnet-py/blob/main/Units.md)\n\n## Units.NET on other platforms\n\nGet the same strongly typed units on other platforms, based on the same [unit definitions](/Common/UnitDefinitions).\n\n| Language | Name | Package \t\t\t\t\t | Repository | Maintainers |\n|----------------------------|-------------|---------------------------------------------------------------------|------------------------------------------------------|--------------|\n| C# | UnitsNet | [nuget](https://www.nuget.org/packages/UnitsNet/) \t\t\t\t\t | [github](https://github.com/angularsen/UnitsNet) | @angularsen |\n| JavaScript /<br>TypeScript | unitsnet-js | [npm](https://www.npmjs.com/package/unitsnet-js) \t\t\t\t\t | [github](https://github.com/haimkastner/unitsnet-js) | @haimkastner |\n| Python | unitsnet-py | [pypi](https://pypi.org/project/unitsnet-py) \t\t\t\t\t | [github](https://github.com/haimkastner/unitsnet-py) | @haimkastner |\n| Golang | unitsnet-go | [pkg.go.dev](https://pkg.go.dev/github.com/haimkastner/unitsnet-go) | [github](https://github.com/haimkastner/unitsnet-go) | @haimkastner |\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A better way to hold unit variables and easily convert to the destination unit",
"version": "0.1.135",
"project_urls": {
"Documentation": "https://github.com/haimkastner/unitsnet-py#readme",
"Homepage": "https://github.com/haimkastner/unitsnet-py",
"Issue Tracker": "https://github.com/haimkastner/unitsnet-py/issues",
"Source": "https://github.com/haimkastner/unitsnet-py"
},
"split_keywords": [
"conversion",
" units-of-measure",
" units",
" quantities",
" unit-converter",
" converter",
" unit",
" measure",
" measures",
" measurement",
" measurements"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5ac4bc413925d2ec32324dae7d678a6dc4810aac67bda0d476e19f4a1445880",
"md5": "46b9761f2dba45bf043d786d5133e4aa",
"sha256": "c99f33a5ef26323a34d8c0ad7679b96b32df4714a7d6f0028567bc2cc2a72f39"
},
"downloads": -1,
"filename": "unitsnet-py-0.1.135.tar.gz",
"has_sig": false,
"md5_digest": "46b9761f2dba45bf043d786d5133e4aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 277127,
"upload_time": "2024-12-09T19:05:15",
"upload_time_iso_8601": "2024-12-09T19:05:15.279083Z",
"url": "https://files.pythonhosted.org/packages/d5/ac/4bc413925d2ec32324dae7d678a6dc4810aac67bda0d476e19f4a1445880/unitsnet-py-0.1.135.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-09 19:05:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "haimkastner",
"github_project": "unitsnet-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "unitsnet-py"
}
JSON
