| Name | semantikon JSON |
| Version |
0.0.4
JSON |
| download |
| home_page | None |
| Summary | semantikon - Ontological type system |
| upload_time | 2024-12-19 08:47:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.13,>=3.9 |
| license | BSD 3-Clause License Copyright (c) 2024, Max-Planck-Institut für Nachhaltige Materialien GmbH - Computational Materials Design (CM) Department All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
pyiron
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# semantikon
## Overview
In the realm of the workflow management systems, there are well defined inputs and outputs for each node. `semantikon` is a Python package to give scientific context to node inputs and outputs by providing type hinting and interpreters. Therefore, it consists of two **fully** separate parts: type hinting and interpreters.
### **Type hinting**
`semantikon` provides a way to define types for any number of input parameters and any number of output values for function via type hinting, in particular: data type, unit and ontological type. Type hinting is done with the function `u`, which **requires** the type, and **optionally** you can define the units and the ontological type. The type hinting is done in the following way:
```python
from semantikon.typing import u
def my_function(
a: u(int, units="meter"),
b: u(int, units="second")
) -> u(int, units="meter/second", label="speed"):
return a / b
```
`semantikon`'s type hinting does not require to follow any particular standard. It only needs to be compatible with the interpreter applied.
There are two possible ways to store the data for `semantikon`. The standard way is to do it by converting all arguments except for the data type as a string, which is the default behaviour. The other way is to store the data as a list, which is turned on by setting `use_list=True`. In most cases, the default behaviour is the safest option; in some cases, especially when the data cannot be represented as a string, you might want to switch on `use_list`, but `semantikon` is still under intensive development, and therefore there is no guarantee that you can retrieve the data across different versions correctly.
### **Interpreters**
#### General interpreter
In order to extract argument information, you can use the functions `parse_input_args` and `parse_output_args`. `parse_input_args` parses the input variables and return a dictionary with the variable names as keys and the variable information as values. `parse_output_args` parses the output variables and return a dictionary with the variable information as values if there is one output variable, or a list of dictionaries if it is a tuple.
Example:
```python
from semantikon.typing import u
from semantikon.converter import parse_input_args, parse_output_args
def my_function(
a: u(int, units="meter"),
b: u(int, units="second")
) -> u(int, units="meter/second", label="speed"):
return a / b
print(parse_input_args(my_function))
print(parse_output_args(my_function))
```
Output:
```python
{'distance': {'units': 'meter', 'label': None, 'uri': None, 'shape': None, 'dtype': <class 'float'>}, 'time': {'units': 'second', 'label': None, 'uri': None, 'shape': None, 'dtype': <class 'float'>}}
{'units': 'meter/second', 'label': 'speed', 'uri': None, 'shape': None, 'dtype': <class 'float'>}
```
Here the output is the same whether `use_list` is set to `True` or `False`. When `use_list` is `False`, you can use additionally any tag that you want to store. When `use_list` is `True`, you can store only the data type, `units`, `label`, `uri`, `shape` and `dtype`.
Future announcement: There will be no distrinction between `use_list=True` and `use_list=False` when the official support of python 3.10 is dropped (i.e. around autumn 2026).
#### Unit conversion with `pint`
`semantikon` provides a way to interpret the types of inputs and outputs of a function via a decorator, in order to check consistency of the types and to convert them if necessary. Currently, `semantikon` provides an interpreter for `pint.UnitRegistry` objects. The interpreter is applied in the following way:
```python
from semantikon.typing import u
from semantikon.converters import units
from pint import UnitRegistry
@units
def my_function(
a: u(int, units="meter"),
b: u(int, units="second")
) -> u(int, units="meter/second", label="speed"):
return a / b
ureg = UnitRegistry()
print(my_function(1 * ureg.meter, 1 * ureg.second))
```
Output: `1.0 meter / second`
The interpreters check all types and, if necessary, convert them to the expected types **before** the function is executed, in order for all possible errors would be raised before the function execution. The interpreters convert the types in the way that the underlying function would receive the raw values.
In case there are multiple outputs, the type hints are to be passed as a tuple (e.g. `(u(int, "meter"), u(int, "second"))`).
Interpreters can distinguish between annotated arguments and non-anotated arguments. If the argument is annotated, the interpreter will try to convert the argument to the expected type. If the argument is not annotated, the interpreter will pass the argument as is.
Regardless of type hints are given or not, the interpreter acts only when the input values contain units and ontological types. If the input values do not contain units and ontological types, the interpreter will pass the input values to the function as is.
Raw data
{
"_id": null,
"home_page": null,
"name": "semantikon",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "pyiron",
"author": null,
"author_email": "Sam Waseda <waseda@mpie.de>",
"download_url": "https://files.pythonhosted.org/packages/c8/93/6065adf3836caf5bc209fc777a1c9bbb19a029d20239e0d29c03322f6034/semantikon-0.0.4.tar.gz",
"platform": null,
"description": "# semantikon\n\n## Overview\n\nIn the realm of the workflow management systems, there are well defined inputs and outputs for each node. `semantikon` is a Python package to give scientific context to node inputs and outputs by providing type hinting and interpreters. Therefore, it consists of two **fully** separate parts: type hinting and interpreters.\n\n### **Type hinting**\n\n`semantikon` provides a way to define types for any number of input parameters and any number of output values for function via type hinting, in particular: data type, unit and ontological type. Type hinting is done with the function `u`, which **requires** the type, and **optionally** you can define the units and the ontological type. The type hinting is done in the following way:\n\n```python\nfrom semantikon.typing import u\n\ndef my_function(\n a: u(int, units=\"meter\"),\n b: u(int, units=\"second\")\n) -> u(int, units=\"meter/second\", label=\"speed\"):\n return a / b\n```\n\n`semantikon`'s type hinting does not require to follow any particular standard. It only needs to be compatible with the interpreter applied.\n\nThere are two possible ways to store the data for `semantikon`. The standard way is to do it by converting all arguments except for the data type as a string, which is the default behaviour. The other way is to store the data as a list, which is turned on by setting `use_list=True`. In most cases, the default behaviour is the safest option; in some cases, especially when the data cannot be represented as a string, you might want to switch on `use_list`, but `semantikon` is still under intensive development, and therefore there is no guarantee that you can retrieve the data across different versions correctly.\n\n\n### **Interpreters**\n\n#### General interpreter\n\nIn order to extract argument information, you can use the functions `parse_input_args` and `parse_output_args`. `parse_input_args` parses the input variables and return a dictionary with the variable names as keys and the variable information as values. `parse_output_args` parses the output variables and return a dictionary with the variable information as values if there is one output variable, or a list of dictionaries if it is a tuple.\n\nExample:\n\n```python\nfrom semantikon.typing import u\nfrom semantikon.converter import parse_input_args, parse_output_args\n\ndef my_function(\n a: u(int, units=\"meter\"),\n b: u(int, units=\"second\")\n) -> u(int, units=\"meter/second\", label=\"speed\"):\n return a / b\n\nprint(parse_input_args(my_function))\nprint(parse_output_args(my_function))\n```\n\nOutput:\n\n```python\n{'distance': {'units': 'meter', 'label': None, 'uri': None, 'shape': None, 'dtype': <class 'float'>}, 'time': {'units': 'second', 'label': None, 'uri': None, 'shape': None, 'dtype': <class 'float'>}}\n{'units': 'meter/second', 'label': 'speed', 'uri': None, 'shape': None, 'dtype': <class 'float'>}\n```\n\nHere the output is the same whether `use_list` is set to `True` or `False`. When `use_list` is `False`, you can use additionally any tag that you want to store. When `use_list` is `True`, you can store only the data type, `units`, `label`, `uri`, `shape` and `dtype`.\n\nFuture announcement: There will be no distrinction between `use_list=True` and `use_list=False` when the official support of python 3.10 is dropped (i.e. around autumn 2026).\n\n#### Unit conversion with `pint`\n\n`semantikon` provides a way to interpret the types of inputs and outputs of a function via a decorator, in order to check consistency of the types and to convert them if necessary. Currently, `semantikon` provides an interpreter for `pint.UnitRegistry` objects. The interpreter is applied in the following way:\n\n```python\nfrom semantikon.typing import u\nfrom semantikon.converters import units\nfrom pint import UnitRegistry\n\n@units\ndef my_function(\n a: u(int, units=\"meter\"),\n b: u(int, units=\"second\")\n) -> u(int, units=\"meter/second\", label=\"speed\"):\n return a / b\n\n\nureg = UnitRegistry()\n\nprint(my_function(1 * ureg.meter, 1 * ureg.second))\n```\n\nOutput: `1.0 meter / second`\n\n\nThe interpreters check all types and, if necessary, convert them to the expected types **before** the function is executed, in order for all possible errors would be raised before the function execution. The interpreters convert the types in the way that the underlying function would receive the raw values.\n\nIn case there are multiple outputs, the type hints are to be passed as a tuple (e.g. `(u(int, \"meter\"), u(int, \"second\"))`).\n\nInterpreters can distinguish between annotated arguments and non-anotated arguments. If the argument is annotated, the interpreter will try to convert the argument to the expected type. If the argument is not annotated, the interpreter will pass the argument as is.\n\nRegardless of type hints are given or not, the interpreter acts only when the input values contain units and ontological types. If the input values do not contain units and ontological types, the interpreter will pass the input values to the function as is.\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2024, Max-Planck-Institut f\u00fcr Nachhaltige Materialien GmbH - Computational Materials Design (CM) Department All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "semantikon - Ontological type system",
"version": "0.0.4",
"project_urls": {
"Documentation": "https://semantikon.readthedocs.io",
"Homepage": "https://pyiron.org/",
"Repository": "https://github.com/pyiron/semantikon"
},
"split_keywords": [
"pyiron"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2d0bc9b49a9de1e24f7f1baf8b36820e94c2b718c60c68d2bd35947854d79be8",
"md5": "a9537301824e97078428d2979f9ec10c",
"sha256": "ce114985164d66eb85dde6d2d77c64b5450b23e8e7446a0d4801a6dccd84603a"
},
"downloads": -1,
"filename": "semantikon-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a9537301824e97078428d2979f9ec10c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 14630,
"upload_time": "2024-12-19T08:47:10",
"upload_time_iso_8601": "2024-12-19T08:47:10.000275Z",
"url": "https://files.pythonhosted.org/packages/2d/0b/c9b49a9de1e24f7f1baf8b36820e94c2b718c60c68d2bd35947854d79be8/semantikon-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c8936065adf3836caf5bc209fc777a1c9bbb19a029d20239e0d29c03322f6034",
"md5": "464c05d2e2ce6c42b338fc68e8ee2f4f",
"sha256": "98b22a3732aed291a3dfdfb0842e05c27cc3299169313c073ef78faf5e2953f8"
},
"downloads": -1,
"filename": "semantikon-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "464c05d2e2ce6c42b338fc68e8ee2f4f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 8073,
"upload_time": "2024-12-19T08:47:12",
"upload_time_iso_8601": "2024-12-19T08:47:12.726034Z",
"url": "https://files.pythonhosted.org/packages/c8/93/6065adf3836caf5bc209fc777a1c9bbb19a029d20239e0d29c03322f6034/semantikon-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-19 08:47:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyiron",
"github_project": "semantikon",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "semantikon"
}
