semantikon 0.0.8__tar.gz

semantikon-0.0.8/LICENSE

@@ -0,0 +1,29 @@
+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.

semantikon-0.0.8/MANIFEST.in

@@ -0,0 +1 @@
+include LICENSE

semantikon-0.0.8/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.2
+Name: semantikon
+Version: 0.0.8
+Summary: semantikon - Ontological type system
+Author-email: Sam Waseda <waseda@mpie.de>
+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.
+        
+Project-URL: Homepage, https://pyiron.org/
+Project-URL: Documentation, https://semantikon.readthedocs.io
+Project-URL: Repository, https://github.com/pyiron/semantikon
+Keywords: pyiron
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Scientific/Engineering
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.3.0,>=2.2.1
+Requires-Dist: pint==0.24.4
+
+# 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(
+    distance: u(int, units="meter"),
+    time: u(int, units="second")
+) -> u(int, units="meter/second", label="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.
+
+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.
+
+You can also type-hint the inputs and outputs of a function using a class, i.e.:
+
+
+```python
+from semantikon.typing import u
+from semantikon.convert import semantikon_class
+
+@semantikon_class
+class MyRecord:
+    distance: u(int, units="meter")
+    time: u(int, units="second")
+    result: u(int, units="meter/second", label="speed")
+
+def my_function(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**
+
+#### 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. `tuple[u(int, "meter"), u(int, "second"))`).
+
+It is not totally garanteed as a functionality, 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-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.
+
+

semantikon-0.0.8/docs/README.md

@@ -0,0 +1,112 @@
+# 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(
+    distance: u(int, units="meter"),
+    time: u(int, units="second")
+) -> u(int, units="meter/second", label="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.
+
+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.
+
+You can also type-hint the inputs and outputs of a function using a class, i.e.:
+
+
+```python
+from semantikon.typing import u
+from semantikon.convert import semantikon_class
+
+@semantikon_class
+class MyRecord:
+    distance: u(int, units="meter")
+    time: u(int, units="second")
+    result: u(int, units="meter/second", label="speed")
+
+def my_function(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**
+
+#### 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. `tuple[u(int, "meter"), u(int, "second"))`).
+
+It is not totally garanteed as a functionality, 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-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.
+
+

semantikon-0.0.8/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = [ "setuptools", "versioneer[toml]==0.29",]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "semantikon"
+description = "semantikon - Ontological type system"
+readme = "docs/README.md"
+keywords = [ "pyiron",]
+requires-python = ">=3.9, <3.13"
+classifiers = [ "Development Status :: 3 - Alpha", "Topic :: Scientific/Engineering", "License :: OSI Approved :: BSD License", "Intended Audience :: Science/Research", "Operating System :: OS Independent", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12",]
+dependencies = [ "numpy>=2.2.1,<2.3.0", "pint==0.24.4",]
+dynamic = [ "version",]
+[[project.authors]]
+name = "Sam Waseda"
+email = "waseda@mpie.de"
+
+[project.license]
+file = "LICENSE"
+
+[project.urls]
+Homepage = "https://pyiron.org/"
+Documentation = "https://semantikon.readthedocs.io"
+Repository = "https://github.com/pyiron/semantikon"
+
+[tool.versioneer]
+VCS = "git"
+style = "pep440-pre"
+versionfile_source = "semantikon/_version.py"
+parentdir_prefix = "semantikon"
+tag_prefix = "semantikon-"
+
+[tool.setuptools.packages.find]
+include = [ "semantikon*",]
+
+[tool.setuptools.dynamic.version]
+attr = "semantikon.__version__"

semantikon-0.0.8/semantikon/__init__.py

@@ -0,0 +1,3 @@
+from . import _version
+
+__version__ = _version.get_versions()["version"]

semantikon-0.0.8/semantikon/_version.py

@@ -0,0 +1,21 @@
+
+# This file was generated by 'versioneer.py' (0.29) from
+# revision-control system data, or from the parent directory name of an
+# unpacked source archive. Distribution tarballs contain a pre-generated copy
+# of this file.
+
+import json
+
+version_json = '''
+{
+ "date": "2025-01-16T06:51:49+0100",
+ "dirty": true,
+ "error": null,
+ "full-revisionid": "d21c1688b4b8b2589bfa7e0927afa90e64699575",
+ "version": "0.0.8"
+}
+'''  # END VERSION_JSON
+
+
+def get_versions():
+    return json.loads(version_json)

semantikon-0.0.8/semantikon/converter.py

@@ -0,0 +1,216 @@
+# coding: utf-8
+# Copyright (c) Max-Planck-Institut für Eisenforschung GmbH - Computational Materials Design (CM) Department
+# Distributed under the terms of "New BSD License", see the LICENSE file.
+
+from pint import Quantity
+import inspect
+from functools import wraps
+from pint.registry_helpers import (
+    _apply_defaults,
+    _parse_wrap_args,
+    _to_units_container,
+    _replace_units,
+)
+from ast import literal_eval
+from typing import get_origin, get_args
+
+__author__ = "Sam Waseda"
+__copyright__ = (
+    "Copyright 2021, Max-Planck-Institut für Eisenforschung GmbH "
+    "- Computational Materials Design (CM) Department"
+)
+__version__ = "1.0"
+__maintainer__ = "Sam Waseda"
+__email__ = "waseda@mpie.de"
+__status__ = "development"
+__date__ = "Aug 21, 2021"
+
+
+def _get_ureg(args, kwargs):
+    for arg in args + tuple(kwargs.values()):
+        if isinstance(arg, Quantity):
+            return arg._REGISTRY
+    return None
+
+
+def parse_metadata(value):
+    """
+    Parse the metadata of a Quantity object.
+
+    Args:
+        value: Quantity object
+
+    Returns:
+        dictionary of the metadata. Available keys are `units`, `label`,
+        `triple`, `uri` and `shape`. See `semantikon.typing.u` for more details.
+    """
+    # When there is only one metadata `use_list=False` must have been used
+    if len(value.__metadata__) == 1 and isinstance(value.__metadata__[0], str):
+        return literal_eval(value.__metadata__[0])
+    else:
+        d = {}
+        for ii in range(len(value.__metadata__[0]) // 2):
+            d[value.__metadata__[0][2 * ii]] = value.__metadata__[0][2 * ii + 1]
+        return d
+
+
+def _meta_to_dict(value):
+    if hasattr(value, "__metadata__"):
+        result = parse_metadata(value)
+        result["dtype"] = value.__args__[0]
+        return result
+    elif value is not inspect.Parameter.empty:
+        return {
+            "units": None,
+            "label": None,
+            "triple": None,
+            "uri": None,
+            "shape": None,
+            "restriction": None,
+            "dtype": value,
+        }
+    else:
+        return None
+
+
+def parse_input_args(func: callable):
+    """
+    Parse the input arguments of a function.
+
+    Args:
+        func: function to be parsed
+
+    Returns:
+        dictionary of the input arguments. Available keys are `units`, `label`,
+        `triple`, `uri` and `shape`. See `semantikon.typing.u` for more details.
+    """
+    return {
+        key: _meta_to_dict(value.annotation)
+        for key, value in inspect.signature(func).parameters.items()
+    }
+
+
+def parse_output_args(func: callable):
+    """
+    Parse the output arguments of a function.
+
+    Args:
+        func: function to be parsed
+
+    Returns:
+        dictionary of the output arguments if there is only one output. Otherwise,
+        a list of dictionaries is returned. Available keys are `units`,
+        `label`, `triple`, `uri` and `shape`. See `semantikon.typing.u` for
+        more details.
+    """
+    sig = inspect.signature(func)
+    if get_origin(sig.return_annotation) is tuple:
+        return tuple([_meta_to_dict(ann) for ann in get_args(sig.return_annotation)])
+    else:
+        return _meta_to_dict(sig.return_annotation)
+
+
+def _get_converter(func):
+    args = []
+    for value in parse_input_args(func).values():
+        if value is not None:
+            args.append(value["units"])
+        else:
+            args.append(None)
+    if any([arg is not None for arg in args]):
+        return _parse_wrap_args(args)
+    else:
+        return None
+
+
+def _get_ret_units(output, ureg, names):
+    if output is None:
+        return None
+    ret = _to_units_container(output["units"], ureg)
+    names = {key: 1.0 * value.units for key, value in names.items()}
+    return ureg.Quantity(1, _replace_units(ret[0], names) if ret[1] else ret[0])
+
+
+def _get_output_units(output, ureg, names):
+    if isinstance(output, tuple):
+        return tuple([_get_ret_units(oo, ureg, names) for oo in output])
+    else:
+        return _get_ret_units(output, ureg, names)
+
+
+def units(func):
+    """
+    Decorator to convert the output of a function to a Quantity object with
+    the specified units.
+
+    Args:
+        func: function to be decorated
+
+    Returns:
+        decorated function
+    """
+    sig = inspect.signature(func)
+    converter = _get_converter(func)
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        ureg = _get_ureg(args, kwargs)
+        if converter is None or ureg is None:
+            return func(*args, **kwargs)
+        args, kwargs = _apply_defaults(sig, args, kwargs)
+        args, kwargs, names = converter(ureg, sig, args, kwargs, strict=False)
+        try:
+            output_units = _get_output_units(parse_output_args(func), ureg, names)
+        except AttributeError:
+            output_units = None
+        if output_units is None:
+            return func(*args, **kwargs)
+        elif isinstance(output_units, tuple):
+            return tuple(
+                [oo * ff for oo, ff in zip(output_units, func(*args, **kwargs))]
+            )
+        else:
+            return output_units * func(*args, **kwargs)
+
+    return wrapper
+
+
+def semantikon_class(cls: type):
+    """
+    A class decorator to append type hints to class attributes.
+
+    Args:
+        cls: class to be decorated
+
+    Returns:
+        The modified class with type hints appended to its attributes.
+
+    Comments:
+
+    >>> from typing import Annotated
+    >>> from semantikon.converter import semantikon_class
+
+    >>> @semantikon_class
+    >>> class Pizza:
+    >>>     price: Annotated[float, "money"]
+    >>>     size: Annotated[float, "dimension"]
+
+    >>>     class Topping:
+    >>>         sauce: Annotated[str, "matter"]
+
+    >>> append_types(Pizza)
+    >>> print(Pizza)
+    >>> print(Pizza.Topping)
+    >>> print(Pizza.size)
+    >>> print(Pizza.price)
+    >>> print(Pizza.Topping.sauce)
+    """
+    for key, value in cls.__dict__.items():
+        if isinstance(value, type):
+            semantikon_class(getattr(cls, key))  # Recursively apply to nested classes
+    try:
+        for key, value in cls.__annotations__.items():
+            setattr(cls, key, value)  # Append type hints to attributes
+    except AttributeError:
+        pass
+    return cls

semantikon-0.0.8/semantikon/typing.py

@@ -0,0 +1,48 @@
+from typing import Annotated, Any
+from semantikon.converter import parse_metadata
+
+__author__ = "Sam Waseda"
+__copyright__ = (
+    "Copyright 2021, Max-Planck-Institut für Eisenforschung GmbH "
+    "- Computational Materials Design (CM) Department"
+)
+__version__ = "1.0"
+__maintainer__ = "Sam Waseda"
+__email__ = "waseda@mpie.de"
+__status__ = "development"
+__date__ = "Aug 21, 2021"
+
+
+def u(
+    type_,
+    /,
+    units: str | None = None,
+    label: str | None = None,
+    triple: tuple[tuple[str, str, str], ...] | tuple[str, str, str] | None = None,
+    uri: str | None = None,
+    shape: tuple[int] | None = None,
+    restriction: tuple[tuple[str, str]] | None = None,
+    use_list: bool = True,
+    **kwargs,
+):
+    parent_result = {}
+    if hasattr(type_, "__metadata__"):
+        parent_result = parse_metadata(type_)
+        type_ = type_.__origin__
+    result = {
+        "units": units,
+        "label": label,
+        "triple": triple,
+        "uri": uri,
+        "shape": shape,
+        "restriction": restriction,
+    }
+    for key, value in parent_result.items():
+        if result[key] is None:
+            result[key] = value
+    result.update(kwargs)
+    if use_list:
+        items = [x for k, v in result.items() for x in [k, v]]
+        return Annotated[type_, items]
+    else:
+        return Annotated[type_, str(result)]

semantikon-0.0.8/semantikon.egg-info/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.2
+Name: semantikon
+Version: 0.0.8
+Summary: semantikon - Ontological type system
+Author-email: Sam Waseda <waseda@mpie.de>
+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.
+        
+Project-URL: Homepage, https://pyiron.org/
+Project-URL: Documentation, https://semantikon.readthedocs.io
+Project-URL: Repository, https://github.com/pyiron/semantikon
+Keywords: pyiron
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Scientific/Engineering
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.3.0,>=2.2.1
+Requires-Dist: pint==0.24.4
+
+# 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(
+    distance: u(int, units="meter"),
+    time: u(int, units="second")
+) -> u(int, units="meter/second", label="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.
+
+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.
+
+You can also type-hint the inputs and outputs of a function using a class, i.e.:
+
+
+```python
+from semantikon.typing import u
+from semantikon.convert import semantikon_class
+
+@semantikon_class
+class MyRecord:
+    distance: u(int, units="meter")
+    time: u(int, units="second")
+    result: u(int, units="meter/second", label="speed")
+
+def my_function(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**
+
+#### 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. `tuple[u(int, "meter"), u(int, "second"))`).
+
+It is not totally garanteed as a functionality, 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-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.
+
+

semantikon-0.0.8/semantikon.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+pyproject.toml
+setup.py
+docs/README.md
+semantikon/__init__.py
+semantikon/_version.py
+semantikon/converter.py
+semantikon/typing.py
+semantikon.egg-info/PKG-INFO
+semantikon.egg-info/SOURCES.txt
+semantikon.egg-info/dependency_links.txt
+semantikon.egg-info/requires.txt
+semantikon.egg-info/top_level.txt

semantikon-0.0.8/semantikon.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

semantikon-0.0.8/semantikon.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy<2.3.0,>=2.2.1
+pint==0.24.4

semantikon-0.0.8/semantikon.egg-info/top_level.txt

@@ -0,0 +1 @@
+semantikon

semantikon-0.0.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

semantikon-0.0.8/setup.py

@@ -0,0 +1,8 @@
+from setuptools import setup
+
+import versioneer
+
+setup(
+    version=versioneer.get_version(),
+    cmdclass=versioneer.get_cmdclass(),
+)