Merge branch 'main' into 2.1.x

Author: atextor

.github/pull_request_template.md

@@ -0,0 +1,26 @@
+## Description
+
+Please include a summary of the changes and the related issue. List any dependencies that are required for this change.
+
+Fixes #(number of issue in GitHub)
+
+## Type of change
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+
+## Checklist:
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+
+## Additional notes:
+
+Add any other notes or comments here.

AUTHORS.md

@@ -2,10 +2,11 @@
 
 The following people have contributed to this repository:
 
-* [Georg Schmidt-Dumont]([email protected])
-* [Nico Makowe](mailto:[email protected])
-* [Aghyad Farrouh](mailto:[email protected])
+* [Hanna Shalamitskaya](mailto:[email protected])
 * [Andreas Textor](mailto:[email protected])
+* [Georg Schmidt-Dumont](mailto:[email protected])
 * [Michele Santoro](mailto:[email protected])
+* Nico Makowe
+* Aghyad Farrouh
 
 Please add yourself to this list, if you contribute to the content.

CONVENTIONS.md

@@ -1,6 +1,7 @@
 # ESMF SDK PY Aspect Model Loader Code Conventions
 
-The following document contains a compilation of conventions and guidelines to format, structure and write code for the ESMF SDK PY Aspect Model Loader.
+The following document contains a compilation of conventions and guidelines to format, 
+structure and write code for the ESMF SDK PY Aspect Model Loader.
 
 ## General Conventions
 Our code conventions are based on the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) but

core/esmf-aspect-meta-model-python/README.md

@@ -1,65 +1,198 @@
 The Aspect Model Loader as part of the Python SDK provided by the [*Eclipse Semantic Modeling Framework*](
 https://projects.eclipse.org/projects/dt.esmf).
 
+<!-- TOC -->
+* [An Aspect of the Meta Model](#an-aspect-of-the-meta-model)
+  * [Set Up SAMM Aspect Meta Model](#set-up-samm-aspect-meta-model)
+    * [Install poetry](#install-poetry)
+    * [Install project dependencies](#install-project-dependencies)
+    * [Download SAMM files](#download-samm-files)
+      * [Download SAMM release](#download-samm-release)
+      * [Download SAMM branch](#download-samm-branch)
+  * [Aspect Meta Model Loader usage](#aspect-meta-model-loader-usage)
+  * [Samm Units](#samm-units)
+  * [SAMM CLI wrapper class](#samm-cli-wrapper-class)
+* [Scripts](#scripts)
+* [Automation Tasks](#automation-tasks)
+  * [tox](#tox)
+  * [GitHub actions](#github-actions)
+    * [Check New Pull Request](#check-new-pull-request)
+    * [Build release](#build-release)
+<!-- TOC -->
+
 # An Aspect of the Meta Model
 
 The `esmf-aspect-model-loader` package provides the Python implementation for the SAMM Aspect Meta Model, or SAMM.
 Each Meta Model element and each Characteristic class is represented by an interface with a corresponding
 implementation.
 
-## Usage
+## Set Up SAMM Aspect Meta Model
 
-An Aspect of the Meta Model can be created as follows using the provided `AspectInstantiator`.
+Before getting started to use the `esmf-aspect-model-loader` library you need to apply some set up actions:
 
-```
-aspect_loader = AspectLoader()
-aspect = aspect_loader.load_aspect_model("absolute/path/to/turtle.ttl");
+Required
+- [Install poetry](#install-poetry)
+- [Install project dependencies](#install-project-dependencies)
+- [Download SAMM files](#download-samm-files)
+Optional
+- [Download SAMM CLI](#download-samm-cli) (needed  to use SAMM CLI functions)
+- [Download SAMM test models](#download-test-models) (for running integration tests)
+
+### Install poetry
+
+`Poetry` used as a dependency management for the `esmf-aspect-model-loader`. Follow the next [instruction](https://python-poetry.org/docs/#installation)
+ to install it.
+
+To check the poetry version run:
+```console
+poetry --version
 ```
 
-or
+### Install project dependencies
 
+Poetry provides convenient functionality for working with dependencies in the project.
+To automatically download and install all the necessary libraries, just run one command:
+```console
+poetry install
 ```
-aspect_loader = AspectLoader()
-aspect = aspect_loader.load_aspect_model_from_multiple_files(["list/of/absolute/paths/to/turtles.ttl"], "aspect_urn");
+It is required to run `poetry install` once in the esmf-aspect-model-loader module.
+
+### Download SAMM files
+
+There are two possibilities to download the SAMM files and extract the Turtle sources for the Meta Model: 
+SAMM release or SAMM branch
+
+#### Download SAMM release
+
+This script downloads a release JAR-file from GitHub, extracts them for further usage in the Aspect Model Loader:
+
+To run script, execute the next command.
+```console
+poetry run download-samm-release
 ```
+The version of the SAMM release is specified in the python script.
+
+Link to all Releases: [SAMM Releases](https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/releases)
 
-## Automatic Deployment
+#### Download SAMM branch
 
-A [GitHub action called 'Release'](https://github.com/eclipse-esmf/esmf-sdk-py-aspect-model-loader/actions/workflows/tagged_release.yml)
-has been set up for the `esmf-aspect-model-loader`. This action checks the code quality by running tests, the [static type checker MyPy](https://github.com/python/mypy) and
-the [code formatter 'Black'](https://github.com/psf/black).
+The script uses the GitHub API and downloads the files from the `main` GitHub branch. 
 
-## Set Up SAMM Aspect Meta Model for development
+If the script is run in a pipeline, it uses a GitHub token to authorize. If the script is run locally, 
+the API is called without a token. This may cause problems because unauthorized API calls are limited.
 
-In order to download the SAMM sources, it is required to run `poetry install` once in the `esmf-aspect-model-loader`
-module. There are two possibilities to download the SAMM files and extract the Turtle sources for the Meta Model.
+Run the next command to download and start working with the Aspect Model Loader.
+```console
+poetry run download-samm-branch
+```
+Link to all branches: [SAMM Releases](https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/branches)
 
-### Possibility 1 (downloading a release)
+## Aspect Meta Model Loader usage
 
-The `download_samm_release` script may be executed with
+An Aspect of the Meta Model can be loaded as follows:
+```python
+from esmf_aspect_meta_model_python import AspectLoader
 
+loader = AspectLoader()
+model_elements = loader.load_aspect_model("absolute/path/to/turtle.ttl")
+aspect = model_elements[0]
+
+# or you can provide an Aspect URN
+
+loader = AspectLoader()
+aspect_urn = "urn:samm:org.eclipse.esmf.samm:aspect.model:0.0.1#AspectName"
+model_elements = loader.load_aspect_model("absolute/path/to/turtle.ttl", aspect_urn)
+aspect = model_elements[0]
 ```
-poetry run download-samm-release
-```  
 
-It downloads a release JAR-file from GitHub and extracts the SAMM Files.
-The version is specified in the python script.
+## Samm Units
+
+SAMMUnitsGraph is a class contains functions for accessing units of measurement.
+```python 
+from esmf_aspect_meta_model_python.samm_meta_model import SammUnitsGraph
 
-Link to all Releases: https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/releases
+units_graph = SammUnitsGraph()
+unit_data = units_graph.get_info("unit:volt")
+# {'preferredName': rdflib.term.Literal('volt', lang='en'), 'commonCode': rdflib.term.Literal('VLT'), ... }
 
-### Possibility 2 (downloading from the repository)
+units_graph.print_description(unit_data)
+# preferredName: volt
+# commonCode: VLT
+# ...
+# symbol: V
+```
+
+## SAMM CLI wrapper class
+
+The SAMM CLI is a command line tool provided number of functions for working with Aspect Models.
 
-It may happen that there is no .jar file that is up to date with the changes of the SAMM.
-This script is an alternative to the `download_samm_release.py` and extracts the files from the repository
-directly instead of using the newest release.
+More detailed information about SAMM CLI functionality can be found in the 
+[SAMM CLI documentation](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/samm-cli.html).
 
-The script uses the GitHub API and downloads the files from the `main` branch. If the script is run in a
-pipeline, it uses a GitHub token to authorize. If the script is run locally, the API is called without a token.
-This may cause problems because unauthorized API calls are limited.
+Python Aspect Model Loader provide a wrapper class to be able to call SAMM CLI functions from the Python code.
+For instance, validation of a model can be done with the following code snippet:
 
-This script can be executed with
+```python
+from esmf_aspect_meta_model_python.samm_cli_functions import SammCli
 
+samm_cli = SammCli()
+model_path = "Paht_to_the_model/Model.ttl"
+samm_cli.validate(model_path)
+# Input model is valid
 ```
-poetry run download-samm-branch
+
+List of SAMMCLI functions:
+- validate
+- to_openapi
+- to_schema
+- to_json
+- to_html
+- to_png
+- to_svg
+
+# Scripts
+
+The Aspect Model Loader provide scripts for downloading some additional code and data.
+Provided scripts:
+ - download-samm-release
+ - download-samm-branch
+ - download-samm-cli
+ - download-test-models
+
+All scripts run like a poetry command. The poetry is available from the folder where [pyproject.toml](pyproject.toml) 
+is located.
+
+# Automation Tasks
+## tox
+
+`tox` is used for the tests automation purpose. There are two environments with different purposes and tests can 
+be running with the tox:
+- pep8: static code checks (PEP8 style) with MyPy and Black
+- py310: unit and integration tests
+
+```console
+# run all checks use the next command
+poetry run tox
+
+# run only pep8 checks
+poetry run tox -e pep8
+
+# run tests
+poetry run tox -e py310
 ```
-to download and start working with the Aspect Model Loader.
+
+## GitHub actions
+
+There are two actions on the GitHub repo:
+- [Check New Pull Request](../../.github/workflows/push_request_check.yml)
+- [Build release](../../.github/workflows/tagged_release.yml)
+
+### Check New Pull Request
+This action run after creation or updating a pull request and run all automation tests with tox command.
+
+### Build release
+Prepare and publish a new release for the `esmf-aspect-model-loader` to the PyPi: 
+[esmf-aspect-model-loader](https://pypi.org/project/esmf-aspect-model-loader/.)
+
+A list of the available releases on the GitHub: 
+[Releases](https://github.com/eclipse-esmf/esmf-sdk-py-aspect-model-loader/releases). 

core/esmf-aspect-meta-model-python/esmf_aspect_meta_model_python/__init__.py

@@ -86,3 +86,4 @@
     DefaultUnit,
 )
 from .loader.aspect_loader import AspectLoader
+from .loader.samm_graph import SAMMGraph