# stringunitconverter
[](https://badge.fury.io/py/stringunitconverter)
[](https://opensource.org/licenses/MIT)
## Goal
Get the multiplication factor
required to convert from one unit to another,
with the units being given as strings.
In short:
make it easy to convert between units.
## Get it
Install with pip using `pip install stringunitconverter`.
For more information,
please see the [PyPI page](https://pypi.org/project/stringunitconverter/).
## Main concepts
- Use strings to specify units
(e.g. 'kN').
- Allow quasi all mathematical combinations of units
(e.g. 'N/m^2').
Math execution order rules should be respected.
- Keep code short (~100 LOC) and unit-independent
and put all unit-related data in a data file (JSON).
It should be easy to add units.
- Focus lies on engineering applications.
Currency conversion etc. is not supported.
- Working concept:
1. Keep a data file with a multiplier for each individual unit
to its [SI base unit(s)](
https://en.wikipedia.org/wiki/SI_base_unit).
For example: ft (to m): 0.3048, mmHg (to Pa): 0.00750.
2. Use this datafile to get the multiplier for each given side to base SI.
This is done by substituting each prefix and unit in the string
with the appropriate numerical value.
The equation, containing only mathematical operations and numbers,
is then evaluated, returning the multiplier.
3. The multiplier for the conversion follows
from dividing the two derived multipliers.
## Limits and notes
- Dimensional correctness is not checked.
- Conversions are always multiplicative.
Therefore, conversions between coordinate systems with a different origin
are not (yet) supported.
For example, between °C and K.
(For this reason, °C and °F are deliberately unsupported; use K.)
Conversions between Hz and s are therefore also not possible,
as this would require inverting the value.
- SI style conventions are followed. Some notes:
- A multiplication is defined using a space ` ` or
a multiplication dot `·`.
The asterisk `*` (Python multiplication symbol) is also supported
- Units not separated by a space or multiplication dot (e.g. 'Nm' for 'N·m')
are not in line with SI style conventions
and are not supported by this parser.
- Power superscripts `²` and `³` are supported, for example `mm²`.
## Supported prefixes and units
Prefixes: y to Y.
Units:
- SI: g, N, s, Pa, bar, A, K, mol, Hz, J, W, C, V, Ohm, S, F, L, rad
- Imperial: oz, psi, mi, ft, in, mil, mph
- Nautical: (NM, nmi), (kn, kt)
- other: mmHg, gf, (°, deg, degree)
- also supported: %
## Functions and examples
```python
def add_unit(unit: str, multiplier: str)
def add_json(filename: str, add_to_existing=False)
def multiplier(a: str, b: str) -> float)
def get_factor(a: str, unsafe=False) -> float)
def unit_to_factor_string(a: str) -> str
```
For documentation of these functions:
please see their help strings.
Two usage examples:
```python3
>>> import stringunitconverter as suc
>>>
>>> suc.multiplier('N/m^2', 'kN/cm^2')
10.0
>>> suc.multiplier('1/kPa', '1/(N/m^2)')
0.001
```
## Contribution and development
The Git remote repository is hosted on
[GitLab](https://gitlab.com/abaeyens/stringunitconverter).
### Testing
Tests are in the directory `tests`
in the root directory.
To run the tests, navigate to the root directory
and run
`pytest`.
This requires a local copy of the repo.
Note that the tests will be run on
the `stringunitconverter` Python package.
This package may or may not point to
the code in the local copy of the repo,
depending on how the package was installed.
### To get this repo locally
1. Clone the repo.
The directory with the project will be located
in the current working directory of the terminal.
```
$ git clone https://gitlab.com/abaeyens/stringunitconverter.git
```
2. Navigate to the created directory.
```
$ cd stringunitconverter
```
## Contact
Have a question, suggestion, ... ?
Your feedback on this project is always appreciated!
Send an e-mail to
[mail@arnebaeyens.com](mailto:mail@arnebaeyens.com).
It is also possible to use the [GitLab issues webpage](
https://gitlab.com/abaeyens/stringunitconverter/-/issues).
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/abaeyens/stringunitconverter",
"name": "stringunitconverter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "unit conversion,conversion",
"author": "Arne Baeyens",
"author_email": "mail@arnebaeyens.com",
"download_url": "https://files.pythonhosted.org/packages/78/dc/61287aeee822097dbbf7b26ffaf3d3bc23bafd4fec44139f04251a805492/stringunitconverter-0.4.tar.gz",
"platform": null,
"description": "# stringunitconverter\n[](https://badge.fury.io/py/stringunitconverter)\n\n[](https://opensource.org/licenses/MIT)\n\n\n## Goal\nGet the multiplication factor\nrequired to convert from one unit to another,\nwith the units being given as strings.\nIn short:\nmake it easy to convert between units.\n\n## Get it\nInstall with pip using `pip install stringunitconverter`.\nFor more information,\nplease see the [PyPI page](https://pypi.org/project/stringunitconverter/).\n\n## Main concepts\n- Use strings to specify units\n (e.g. 'kN').\n- Allow quasi all mathematical combinations of units\n (e.g. 'N/m^2').\n Math execution order rules should be respected.\n- Keep code short (~100 LOC) and unit-independent\n and put all unit-related data in a data file (JSON).\n It should be easy to add units.\n- Focus lies on engineering applications.\n Currency conversion etc. is not supported.\n- Working concept:\n 1. Keep a data file with a multiplier for each individual unit\n to its [SI base unit(s)](\n https://en.wikipedia.org/wiki/SI_base_unit).\n For example: ft (to m): 0.3048, mmHg (to Pa): 0.00750.\n 2. Use this datafile to get the multiplier for each given side to base SI.\n This is done by substituting each prefix and unit in the string\n with the appropriate numerical value.\n The equation, containing only mathematical operations and numbers,\n is then evaluated, returning the multiplier.\n 3. The multiplier for the conversion follows\n from dividing the two derived multipliers.\n\n## Limits and notes\n- Dimensional correctness is not checked.\n- Conversions are always multiplicative.\n Therefore, conversions between coordinate systems with a different origin\n are not (yet) supported.\n For example, between \u00b0C and K.\n (For this reason, \u00b0C and \u00b0F are deliberately unsupported; use K.)\n Conversions between Hz and s are therefore also not possible,\n as this would require inverting the value.\n- SI style conventions are followed. Some notes:\n - A multiplication is defined using a space ` ` or\n a multiplication dot `\u00b7`.\n The asterisk `*` (Python multiplication symbol) is also supported\n - Units not separated by a space or multiplication dot (e.g. 'Nm' for 'N\u00b7m')\n are not in line with SI style conventions\n and are not supported by this parser.\n- Power superscripts `\u00b2` and `\u00b3` are supported, for example `mm\u00b2`. \n\n\n## Supported prefixes and units\nPrefixes: y to Y. \nUnits:\n- SI: g, N, s, Pa, bar, A, K, mol, Hz, J, W, C, V, Ohm, S, F, L, rad\n- Imperial: oz, psi, mi, ft, in, mil, mph\n- Nautical: (NM, nmi), (kn, kt)\n- other: mmHg, gf, (\u00b0, deg, degree)\n- also supported: %\n\n\n## Functions and examples\n```python\ndef add_unit(unit: str, multiplier: str)\n\ndef add_json(filename: str, add_to_existing=False)\n\ndef multiplier(a: str, b: str) -> float)\n\ndef get_factor(a: str, unsafe=False) -> float)\n\ndef unit_to_factor_string(a: str) -> str\n```\n\nFor documentation of these functions:\nplease see their help strings.\n\nTwo usage examples:\n```python3\n>>> import stringunitconverter as suc\n>>>\n>>> suc.multiplier('N/m^2', 'kN/cm^2')\n10.0\n>>> suc.multiplier('1/kPa', '1/(N/m^2)')\n0.001\n```\n\n\n## Contribution and development\nThe Git remote repository is hosted on\n[GitLab](https://gitlab.com/abaeyens/stringunitconverter).\n\n### Testing\nTests are in the directory `tests`\nin the root directory.\nTo run the tests, navigate to the root directory\nand run\n`pytest`.\n\nThis requires a local copy of the repo.\nNote that the tests will be run on\nthe `stringunitconverter` Python package.\nThis package may or may not point to\nthe code in the local copy of the repo,\ndepending on how the package was installed.\n\n\n### To get this repo locally\n1. Clone the repo.\nThe directory with the project will be located\nin the current working directory of the terminal.\n ```\n $ git clone https://gitlab.com/abaeyens/stringunitconverter.git\n ```\n2. Navigate to the created directory.\n ```\n $ cd stringunitconverter\n ```\n\n\n## Contact\nHave a question, suggestion, ... ?\nYour feedback on this project is always appreciated!\nSend an e-mail to\n[mail@arnebaeyens.com](mailto:mail@arnebaeyens.com).\n\nIt is also possible to use the [GitLab issues webpage](\n https://gitlab.com/abaeyens/stringunitconverter/-/issues).\n",
"bugtrack_url": null,
"license": "",
"summary": "Unit converter: Returns multiplier for unit conversion, with units defined as strings.",
"version": "0.4",
"project_urls": {
"Homepage": "https://gitlab.com/abaeyens/stringunitconverter"
},
"split_keywords": [
"unit conversion",
"conversion"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a896a0f30ac5ca5d1725dfe43aa4cd11a84b9c7dd1edc0ec5db9ffeabd0e893d",
"md5": "d57606302ae1508eec52d3ffd75481c3",
"sha256": "c30ea855106bd119868a33b18e47d51a404085b3b618a271a8b8b4b097aee346"
},
"downloads": -1,
"filename": "stringunitconverter-0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d57606302ae1508eec52d3ffd75481c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7802,
"upload_time": "2023-05-10T22:31:28",
"upload_time_iso_8601": "2023-05-10T22:31:28.510334Z",
"url": "https://files.pythonhosted.org/packages/a8/96/a0f30ac5ca5d1725dfe43aa4cd11a84b9c7dd1edc0ec5db9ffeabd0e893d/stringunitconverter-0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "78dc61287aeee822097dbbf7b26ffaf3d3bc23bafd4fec44139f04251a805492",
"md5": "b01d767c79b65efb63d226bad43a93f9",
"sha256": "ff85dc967e8aee97826ea45bb3557070a63d7863b0e0b43b9d42e48d847edb9d"
},
"downloads": -1,
"filename": "stringunitconverter-0.4.tar.gz",
"has_sig": false,
"md5_digest": "b01d767c79b65efb63d226bad43a93f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 9722,
"upload_time": "2023-05-10T22:31:29",
"upload_time_iso_8601": "2023-05-10T22:31:29.857852Z",
"url": "https://files.pythonhosted.org/packages/78/dc/61287aeee822097dbbf7b26ffaf3d3bc23bafd4fec44139f04251a805492/stringunitconverter-0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-10 22:31:29",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "abaeyens",
"gitlab_project": "stringunitconverter",
"lcname": "stringunitconverter"
}
JSON