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.
## Set Up SAMM Aspect Meta Model
Before getting started to use the `esmf-aspect-model-loader` library you need to apply some set up actions:
Required
- [Install poetry](#install-poetry)
- [Install project dependencies](#install-project-dependencies)
- [Download SAMM files](#download-samm-files)
### 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
```
### 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
```
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)
#### Download SAMM branch
The script uses the GitHub API and downloads the files from the `main` GitHub 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.
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)
## Aspect Meta Model Loader usage
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]
```
## Samm Units
SAMMUnitsGraph is a class contains functions for accessing units of measurement.
```python
from esmf_aspect_meta_model_python.samm_meta_model import units
unit_name = "unit:volt"
units.print_description(units.get_info(unit_name))
# preferredName: volt
# commonCode: VLT
# ...
# symbol: V
# Get unit data as dictionary
volt_info = units.get_info("unit:volt")
# {'preferredName': rdflib.term.Literal('volt', lang='en'), 'commonCode': rdflib.term.Literal('VLT'), ... }
units.print_description(volt_info)
# 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.
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).
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:
```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
```
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
```
## 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).
Raw data
{
"_id": null,
"home_page": "https://projects.eclipse.org/projects/dt.esmf",
"name": "esmf-aspect-model-loader",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "samm, esmf, digital twin, idta, model loader, semantic api, semantics, aspect",
"author": "Eclipse Semantic Modeling Framework",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5d/ab/618e0e6ebfe6ba0779e5a822d286d536122a3f79d159f5e1eee91c915098/esmf_aspect_model_loader-2.1.5.tar.gz",
"platform": null,
"description": "The Aspect Model Loader as part of the Python SDK provided by the [*Eclipse Semantic Modeling Framework*](\nhttps://projects.eclipse.org/projects/dt.esmf).\n\n<!-- TOC -->\n* [An Aspect of the Meta Model](#an-aspect-of-the-meta-model)\n * [Set Up SAMM Aspect Meta Model](#set-up-samm-aspect-meta-model)\n * [Install poetry](#install-poetry)\n * [Install project dependencies](#install-project-dependencies)\n * [Download SAMM files](#download-samm-files)\n * [Download SAMM release](#download-samm-release)\n * [Download SAMM branch](#download-samm-branch)\n * [Aspect Meta Model Loader usage](#aspect-meta-model-loader-usage)\n * [Samm Units](#samm-units)\n * [SAMM CLI wrapper class](#samm-cli-wrapper-class)\n* [Scripts](#scripts)\n* [Automation Tasks](#automation-tasks)\n * [tox](#tox)\n * [GitHub actions](#github-actions)\n * [Check New Pull Request](#check-new-pull-request)\n * [Build release](#build-release)\n<!-- TOC -->\n\n# An Aspect of the Meta Model\n\nThe `esmf-aspect-model-loader` package provides the Python implementation for the SAMM Aspect Meta Model, or SAMM.\nEach Meta Model element and each Characteristic class is represented by an interface with a corresponding\nimplementation.\n\n## Set Up SAMM Aspect Meta Model\n\nBefore getting started to use the `esmf-aspect-model-loader` library you need to apply some set up actions:\n\nRequired\n- [Install poetry](#install-poetry)\n- [Install project dependencies](#install-project-dependencies)\n- [Download SAMM files](#download-samm-files)\n\n### Install poetry\n\n`Poetry` used as a dependency management for the `esmf-aspect-model-loader`. Follow the next [instruction](https://python-poetry.org/docs/#installation)\n to install it.\n\nTo check the poetry version run:\n```console\npoetry --version\n```\n\n### Install project dependencies\n\nPoetry provides convenient functionality for working with dependencies in the project.\nTo automatically download and install all the necessary libraries, just run one command:\n```console\npoetry install\n```\nIt is required to run `poetry install` once in the esmf-aspect-model-loader module.\n\n### Download SAMM files\n\nThere are two possibilities to download the SAMM files and extract the Turtle sources for the Meta Model: \nSAMM release or SAMM branch\n\n#### Download SAMM release\n\nThis script downloads a release JAR-file from GitHub, extracts them for further usage in the Aspect Model Loader:\n\nTo run script, execute the next command.\n```console\npoetry run download-samm-release\n```\nThe version of the SAMM release is specified in the python script.\n\nLink to all Releases: [SAMM Releases](https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/releases)\n\n#### Download SAMM branch\n\nThe script uses the GitHub API and downloads the files from the `main` GitHub branch. \n\nIf the script is run in a pipeline, it uses a GitHub token to authorize. If the script is run locally, \nthe API is called without a token. This may cause problems because unauthorized API calls are limited.\n\nRun the next command to download and start working with the Aspect Model Loader.\n```console\npoetry run download-samm-branch\n```\nLink to all branches: [SAMM Releases](https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/branches)\n\n## Aspect Meta Model Loader usage\n\nAn Aspect of the Meta Model can be loaded as follows:\n```python\nfrom esmf_aspect_meta_model_python import AspectLoader\n\nloader = AspectLoader()\nmodel_elements = loader.load_aspect_model(\"absolute/path/to/turtle.ttl\")\naspect = model_elements[0]\n\n# or you can provide an Aspect URN\n\nloader = AspectLoader()\naspect_urn = \"urn:samm:org.eclipse.esmf.samm:aspect.model:0.0.1#AspectName\"\nmodel_elements = loader.load_aspect_model(\"absolute/path/to/turtle.ttl\", aspect_urn)\naspect = model_elements[0]\n```\n\n## Samm Units\n\nSAMMUnitsGraph is a class contains functions for accessing units of measurement.\n```python \nfrom esmf_aspect_meta_model_python.samm_meta_model import units\n\nunit_name = \"unit:volt\"\nunits.print_description(units.get_info(unit_name))\n# preferredName: volt\n# commonCode: VLT\n# ...\n# symbol: V\n\n# Get unit data as dictionary\nvolt_info = units.get_info(\"unit:volt\")\n# {'preferredName': rdflib.term.Literal('volt', lang='en'), 'commonCode': rdflib.term.Literal('VLT'), ... }\n\nunits.print_description(volt_info)\n# preferredName: volt\n# commonCode: VLT\n# ...\n# symbol: V\n```\n\n## SAMM CLI wrapper class\n\nThe SAMM CLI is a command line tool provided number of functions for working with Aspect Models.\n\nMore detailed information about SAMM CLI functionality can be found in the \n[SAMM CLI documentation](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/samm-cli.html).\n\nPython Aspect Model Loader provide a wrapper class to be able to call SAMM CLI functions from the Python code.\nFor instance, validation of a model can be done with the following code snippet:\n\n```python\nfrom esmf_aspect_meta_model_python.samm_cli_functions import SammCli\n\nsamm_cli = SammCli()\nmodel_path = \"Paht_to_the_model/Model.ttl\"\nsamm_cli.validate(model_path)\n# Input model is valid\n```\n\nList of SAMMCLI functions:\n- validate\n- to_openapi\n- to_schema\n- to_json\n- to_html\n- to_png\n- to_svg\n\n# Scripts\n\nThe Aspect Model Loader provide scripts for downloading some additional code and data.\nProvided scripts:\n - download-samm-release\n - download-samm-branch\n - download-samm-cli\n - download-test-models\n\nAll scripts run like a poetry command. The poetry is available from the folder where [pyproject.toml](pyproject.toml) \nis located.\n\n# Automation Tasks\n## tox\n\n`tox` is used for the tests automation purpose. There are two environments with different purposes and tests can \nbe running with the tox:\n- pep8: static code checks (PEP8 style) with MyPy and Black\n- py310: unit and integration tests\n\n```console\n# run all checks use the next command\npoetry run tox\n\n# run only pep8 checks\npoetry run tox -e pep8\n\n# run tests\npoetry run tox -e py310\n```\n\n## GitHub actions\n\nThere are two actions on the GitHub repo:\n- [Check New Pull Request](../../.github/workflows/push_request_check.yml)\n- [Build release](../../.github/workflows/tagged_release.yml)\n\n### Check New Pull Request\nThis action run after creation or updating a pull request and run all automation tests with tox command.\n\n### Build release\nPrepare and publish a new release for the `esmf-aspect-model-loader` to the PyPi: \n[esmf-aspect-model-loader](https://pypi.org/project/esmf-aspect-model-loader/.)\n\nA list of the available releases on the GitHub: \n[Releases](https://github.com/eclipse-esmf/esmf-sdk-py-aspect-model-loader/releases). \n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "Load Aspect Models based on the Semantic Aspect Meta Model",
"version": "2.1.5",
"project_urls": {
"Documentation": "https://eclipse-esmf.github.io/python-sdk-guide/index.html",
"Homepage": "https://projects.eclipse.org/projects/dt.esmf",
"Repository": "https://github.com/bci-oss/esmf-sdk-py-aspect-model-loader"
},
"split_keywords": [
"samm",
" esmf",
" digital twin",
" idta",
" model loader",
" semantic api",
" semantics",
" aspect"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d33be7fef2c1d3d066ef4ec0cde5f420cb6796144ae83ce6f49e83ce48f4405",
"md5": "9cd8c6f62eaf13d0bcb140048838adeb",
"sha256": "bd14c2678c49239adc4e82bd80a6f90699028cd451181daed280e15a4e01f475"
},
"downloads": -1,
"filename": "esmf_aspect_model_loader-2.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9cd8c6f62eaf13d0bcb140048838adeb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 458353,
"upload_time": "2024-07-26T11:18:28",
"upload_time_iso_8601": "2024-07-26T11:18:28.236123Z",
"url": "https://files.pythonhosted.org/packages/5d/33/be7fef2c1d3d066ef4ec0cde5f420cb6796144ae83ce6f49e83ce48f4405/esmf_aspect_model_loader-2.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5dab618e0e6ebfe6ba0779e5a822d286d536122a3f79d159f5e1eee91c915098",
"md5": "fe33510f5ffb1300eb8faabe08078039",
"sha256": "b4967d1205bd52a2b83a1715605a072d2ea1b514e8cd86e905419404056cf214"
},
"downloads": -1,
"filename": "esmf_aspect_model_loader-2.1.5.tar.gz",
"has_sig": false,
"md5_digest": "fe33510f5ffb1300eb8faabe08078039",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 333375,
"upload_time": "2024-07-26T11:18:29",
"upload_time_iso_8601": "2024-07-26T11:18:29.752765Z",
"url": "https://files.pythonhosted.org/packages/5d/ab/618e0e6ebfe6ba0779e5a822d286d536122a3f79d159f5e1eee91c915098/esmf_aspect_model_loader-2.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-26 11:18:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bci-oss",
"github_project": "esmf-sdk-py-aspect-model-loader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "esmf-aspect-model-loader"
}
JSON
