| Name | semantikon JSON |
| Version |
0.0.21
JSON |
| download |
| home_page | None |
| Summary | semantikon - Ontological type system |
| upload_time | 2025-07-19 19:53:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.14,>=3.10 |
| 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
[](https://github.com/pyiron/semantikon/actions/workflows/push-pull.yml)
[](https://codecov.io/gh/pyiron/semantikon)
<img src="../images/logo.jpeg" alt="Logo" width="300"/>
## Motivation
Let's take a look at the following function:
```python
def get_speed(distance: float, time: float) -> float:
return distance / time
```
For you as a human, it is clear that this is a function to calculate the speed for a given distance and a time. But for a computer, it is just a function that takes two floats and returns a float. The computer does not know what the inputs and outputs mean. This is where `semantikon` comes in. It provides a way to give scientific context to the inputs and outputs, as well as to the function itself.
## Installation
You can install `semantikon` via `pip`:
```bash
pip install semantikon
```
You can also install `semantikon` via `conda`:
```bash
conda install -c conda-forge 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.metadata import u
>>> from rdflib import Namespace
>>>
>>> EX = Namespace("http://example.org/")
>>>
>>> def get_speed(
... distance: u(float, units="meter", uri=EX.distance),
... time: u(float, units="second", uri=EX.time),
... ) -> u(float, units="meter/second", label="speed", uri=EX.speed):
... return distance / time
```
`semantikon`'s type hinting does not require to follow any particular standard. It only needs to be compatible with the interpreter applied (s. below).
You can also type-hint the inputs and outputs of a function using a class, i.e.:
```python
>>> from semantikon.metadata import u
>>> from semantikon.converter import semantikon_class
>>> from rdflib import Namespace
>>>
>>> EX = Namespace("http://example.org/")
>>>
>>> @semantikon_class
... class MyRecord:
... distance: u(float, units="meter", uri=EX.distance)
... time: u(float, units="second", uri=EX.time)
... result: u(float, units="meter/second", label="speed", uri=EX.speed)
>>>
>>> def get_speed(distance: MyRecord.distance, time: MyRecord.time) -> MyRecord.result:
... return distance / time
```
This is equivalent to the previous example. Moreover, if you need to modify some parameters, you can use `u` again, e.g. `u(MyRecord.distance, units="kilometer")`.
### **Interpreters**
Interpreters are wrappers or decorators that inspect and process type-hinted metadata at runtime.
#### 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 returns a dictionary with the variable information if there is a single output variable, or a list of dictionaries if it is a tuple.
Example:
```python
>>> from semantikon.metadata import u
>>> from semantikon.converter import parse_input_args, parse_output_args
>>> from rdflib import Namespace
>>>
>>> EX = Namespace("http://example.org/")
>>>
>>> def get_speed(
... a: u(float, units="meter", uri=EX.distance),
... b: u(float, units="second", uri=EX.time),
... ) -> u(float, units="meter/second", label="speed", uri=EX.speed):
... return a / b
>>>
>>> print(dict(sorted({k: dict(sorted(v.items())) for k, v in parse_input_args(get_speed).items()}.items())))
{'a': {'dtype': <class 'float'>, 'units': 'meter', 'uri': rdflib.term.URIRef('http://example.org/distance')}, 'b': {'dtype': <class 'float'>, 'units': 'second', 'uri': rdflib.term.URIRef('http://example.org/time')}}
>>> print(dict(sorted(parse_output_args(get_speed).items())))
{'dtype': <class 'float'>, 'label': 'speed', 'units': 'meter/second', 'uri': rdflib.term.URIRef('http://example.org/speed')}
```
#### 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.metadata import u
>>> from semantikon.converter import units
>>> from pint import UnitRegistry
>>>
>>> @units
... def get_speed(
... a: u(float, units="meter"),
... b: u(float, units="second")
... ) -> u(float, units="meter/second", label="speed"):
... return a / b
>>>
>>> ureg = UnitRegistry()
>>>
>>> print(get_speed(1 * ureg.meter, 1 * ureg.second))
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. `tuple[u(float, "meter"), u(float, "second"))`).
It is not fully guaranteed as a feature, but relative units as given [on this page](https://pint.readthedocs.io/en/0.10.1/wrapping.html#specifying-relations-between-arguments) can be also used.
Interpreters can distinguish between annotated arguments and non-annotated 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 whether type hints are provided, 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.
#### Knowledge graph
For the creation of knowledge graphs, take a look at the [notebook](../notebooks/knowledge_graph.ipynb) in the `notebooks` folder. It shows how to create a knowledge graph from the type hints of a function and how to visualize it, as well as how to type check using the ontology of your choice.
## License
This project is licensed under the BSD 3-Clause License - see the [LICENSE](../LICENSE) file for details.
Copyright (c) 2025, Max-Planck-Institut für Nachhaltige Materialien GmbH - Computational Materials Design (CM) Department
Raw data
{
"_id": null,
"home_page": null,
"name": "semantikon",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "pyiron",
"author": null,
"author_email": "Sam Waseda <waseda@mpie.de>",
"download_url": "https://files.pythonhosted.org/packages/4e/01/985832f940349cd38bbb0f07d32149482bd955d2fec68b98232da75c42b8/semantikon-0.0.21.tar.gz",
"platform": null,
"description": "# semantikon\n\n[](https://github.com/pyiron/semantikon/actions/workflows/push-pull.yml)\n[](https://codecov.io/gh/pyiron/semantikon)\n\n<img src=\"../images/logo.jpeg\" alt=\"Logo\" width=\"300\"/>\n\n\n## Motivation\n\nLet's take a look at the following function:\n\n```python\ndef get_speed(distance: float, time: float) -> float:\n return distance / time\n```\n\nFor you as a human, it is clear that this is a function to calculate the speed for a given distance and a time. But for a computer, it is just a function that takes two floats and returns a float. The computer does not know what the inputs and outputs mean. This is where `semantikon` comes in. It provides a way to give scientific context to the inputs and outputs, as well as to the function itself.\n\n\n## Installation\n\nYou can install `semantikon` via `pip`:\n\n```bash\npip install semantikon\n```\n\nYou can also install `semantikon` via `conda`:\n\n```bash\nconda install -c conda-forge semantikon\n```\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\n>>> from semantikon.metadata import u\n>>> from rdflib import Namespace\n>>>\n>>> EX = Namespace(\"http://example.org/\")\n>>>\n>>> def get_speed(\n... distance: u(float, units=\"meter\", uri=EX.distance),\n... time: u(float, units=\"second\", uri=EX.time),\n... ) -> u(float, units=\"meter/second\", label=\"speed\", uri=EX.speed):\n... return distance / time\n\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 (s. below).\n\nYou can also type-hint the inputs and outputs of a function using a class, i.e.:\n\n```python\n>>> from semantikon.metadata import u\n>>> from semantikon.converter import semantikon_class\n>>> from rdflib import Namespace\n>>>\n>>> EX = Namespace(\"http://example.org/\")\n>>>\n>>> @semantikon_class\n... class MyRecord:\n... distance: u(float, units=\"meter\", uri=EX.distance)\n... time: u(float, units=\"second\", uri=EX.time)\n... result: u(float, units=\"meter/second\", label=\"speed\", uri=EX.speed)\n>>>\n>>> def get_speed(distance: MyRecord.distance, time: MyRecord.time) -> MyRecord.result:\n... return distance / time\n\n```\n\nThis is equivalent to the previous example. Moreover, if you need to modify some parameters, you can use `u` again, e.g. `u(MyRecord.distance, units=\"kilometer\")`.\n\n### **Interpreters**\n\nInterpreters are wrappers or decorators that inspect and process type-hinted metadata at runtime.\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 returns a dictionary with the variable information if there is a single output variable, or a list of dictionaries if it is a tuple.\n\nExample:\n\n```python\n>>> from semantikon.metadata import u\n>>> from semantikon.converter import parse_input_args, parse_output_args\n>>> from rdflib import Namespace\n>>>\n>>> EX = Namespace(\"http://example.org/\")\n>>>\n>>> def get_speed(\n... a: u(float, units=\"meter\", uri=EX.distance),\n... b: u(float, units=\"second\", uri=EX.time),\n... ) -> u(float, units=\"meter/second\", label=\"speed\", uri=EX.speed):\n... return a / b\n>>>\n>>> print(dict(sorted({k: dict(sorted(v.items())) for k, v in parse_input_args(get_speed).items()}.items())))\n{'a': {'dtype': <class 'float'>, 'units': 'meter', 'uri': rdflib.term.URIRef('http://example.org/distance')}, 'b': {'dtype': <class 'float'>, 'units': 'second', 'uri': rdflib.term.URIRef('http://example.org/time')}}\n\n>>> print(dict(sorted(parse_output_args(get_speed).items())))\n{'dtype': <class 'float'>, 'label': 'speed', 'units': 'meter/second', 'uri': rdflib.term.URIRef('http://example.org/speed')}\n\n```\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\n>>> from semantikon.metadata import u\n>>> from semantikon.converter import units\n>>> from pint import UnitRegistry\n>>>\n>>> @units\n... def get_speed(\n... a: u(float, units=\"meter\"),\n... b: u(float, units=\"second\")\n... ) -> u(float, units=\"meter/second\", label=\"speed\"):\n... return a / b\n>>>\n>>> ureg = UnitRegistry()\n>>>\n>>> print(get_speed(1 * ureg.meter, 1 * ureg.second))\n1.0 meter / second\n\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. `tuple[u(float, \"meter\"), u(float, \"second\"))`).\n\nIt is not fully guaranteed as a feature, but relative units as given [on this page](https://pint.readthedocs.io/en/0.10.1/wrapping.html#specifying-relations-between-arguments) can be also used.\n\nInterpreters can distinguish between annotated arguments and non-annotated 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 whether type hints are provided, 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#### Knowledge graph\n\nFor the creation of knowledge graphs, take a look at the [notebook](../notebooks/knowledge_graph.ipynb) in the `notebooks` folder. It shows how to create a knowledge graph from the type hints of a function and how to visualize it, as well as how to type check using the ontology of your choice.\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the [LICENSE](../LICENSE) file for details.\n\nCopyright (c) 2025, Max-Planck-Institut f\u00fcr Nachhaltige Materialien GmbH - Computational Materials Design (CM) Department\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License\n \n Copyright (c) 2024, Max-Planck-Institut f\u00fcr Nachhaltige Materialien GmbH - Computational Materials Design (CM) Department\n All rights reserved.\n \n Redistribution and use in source and binary forms, with or without\n modification, are permitted provided that the following conditions are met:\n \n * Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n \n * Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimer in the documentation\n and/or other materials provided with the distribution.\n \n * Neither the name of the copyright holder nor the names of its\n contributors may be used to endorse or promote products derived from\n this software without specific prior written permission.\n \n THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\n AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\n DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\n FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\n SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\n CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\n OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\n OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n ",
"summary": "semantikon - Ontological type system",
"version": "0.0.21",
"project_urls": {
"Documentation": "https://semantikon.readthedocs.io",
"Homepage": "https://pyiron.org/",
"Repository": "https://github.com/pyiron/semantikon"
},
"split_keywords": [
"pyiron"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a5168c623236a850a2bb9658c23555c31da6e4f0fd6c9db8a3c3dc762db976e3",
"md5": "c5399e2c8ed7b9fcceb9a019e7399b2e",
"sha256": "8fde339b79519951ad10a07bdf5182d18baa574fb05a766004acf20908f22a14"
},
"downloads": -1,
"filename": "semantikon-0.0.21-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5399e2c8ed7b9fcceb9a019e7399b2e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 77296,
"upload_time": "2025-07-19T19:53:53",
"upload_time_iso_8601": "2025-07-19T19:53:53.899178Z",
"url": "https://files.pythonhosted.org/packages/a5/16/8c623236a850a2bb9658c23555c31da6e4f0fd6c9db8a3c3dc762db976e3/semantikon-0.0.21-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4e01985832f940349cd38bbb0f07d32149482bd955d2fec68b98232da75c42b8",
"md5": "71b174d84378bf501a3f5929056bca16",
"sha256": "6335ecbde5acdea134e261dfce280868f34093ebb016f3f6ad7043f99ea7a9a0"
},
"downloads": -1,
"filename": "semantikon-0.0.21.tar.gz",
"has_sig": false,
"md5_digest": "71b174d84378bf501a3f5929056bca16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 71202,
"upload_time": "2025-07-19T19:53:55",
"upload_time_iso_8601": "2025-07-19T19:53:55.485326Z",
"url": "https://files.pythonhosted.org/packages/4e/01/985832f940349cd38bbb0f07d32149482bd955d2fec68b98232da75c42b8/semantikon-0.0.21.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 19:53:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyiron",
"github_project": "semantikon",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "semantikon"
}
