Metadata-Version: 2.4
Name: esmf-aspect-model-loader
Version: 2.3.0
Summary: Load Aspect Models based on the Semantic Aspect Meta Model
Project-URL: Homepage, https://projects.eclipse.org/projects/dt.esmf
Project-URL: Repository, https://github.com/eclipse-esmf/esmf-sdk-py-aspect-model-loader
Project-URL: Documentation, https://eclipse-esmf.github.io/python-sdk-guide/index.html
Author: Eclipse Semantic Modeling Framework, Nico Makowe, Aghyad Farrouh
Author-email: Hanna Shalamitskaya <external.Hanna.Shalamitskaya@de.bosch.com>, Oleksandr Muzyka <external.Oleksandr.Muzyka@bosch.com>, Andreas Textor <Andreas.Textor@de.bosch.com>, Georg Schmidt-Dumont <Georg.Schmidt-Dumont@de.bosch.com>, Michele Santoro <michele.santoro@de.bosch.com>, Lars Heppler <Lars.Heppler@de.bosch.com>
License-Expression: MPL-2.0
Keywords: aspect,digital twin,esmf,idta,model loader,samm,semantic api,semantics
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: <4.0,>=3.10
Requires-Dist: rdflib==7.6.0
Requires-Dist: requests==2.34.2
Description-Content-Type: text/markdown

The Aspect Model Loader as part of the Python SDK provided by the [*Eclipse Semantic Modeling Framework*](
https://projects.eclipse.org/projects/dt.esmf).

# 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.

## Documentation

* Check the [developer documentation](https://eclipse-esmf.github.io)
* Check the SAMM [specification](https://eclipse-esmf.github.io/samm-specification/snapshot/index.html)
* Having issues with the ESMF SDK Python Aspect Model Loader? Open a [GitHub issue](https://github.com/eclipse-esmf/esmf-sdk-py-aspect-model-loader/issues).

## 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 uv](#install-uv)
- [Install project dependencies](#install-project-dependencies)
- [Download SAMM files](#download-samm-files)

### Install uv

`uv` is used as the dependency manager for the `esmf-aspect-model-loader`. Follow the next [instruction](https://docs.astral.sh/uv/getting-started/installation/)
 to install it.

To check the uv version run:
```console
uv --version
```

### Install project dependencies

uv provides convenient functionality for working with dependencies in the project.
To automatically create a virtual environment and install all the necessary libraries, just run one command:
```console
uv sync
```
It is required to run `uv sync` 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
uv 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
uv run download-samm-branch
```
Link to all branches: [SAMM Releases](https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/branches)

## SAMM Aspect Model Graph usage

SAMM Aspect Model Graph is a class that allows you to load and interact with the Semantic Data Aspect Meta Model graph. 
Below is an example of how to use SAMM Aspect Model Graph in your Python code:
```python
from esmf_aspect_meta_model_python import SAMMGraph

# Define the path to your Turtle file
model_path = "absolute/path/to/turtle.ttl"

# Create an instance of SAMMGraph
samm_graph = SAMMGraph()

# Parse the Turtle file to load the graph
samm_graph.parse(model_path)

# Load the aspect model from the graph
aspect = samm_graph.load_aspect_model()
```

The `load_model_elements` method in the SAMMGraph class creates Python objects to represent all nodes from the Aspect 
model graph. It retrieves all SAMM elements from the RDF graph and converts them into structured Python objects.
```python
from esmf_aspect_meta_model_python import SAMMGraph

# Define the path to your Turtle file
model_path = "absolute/path/to/turtle.ttl"

# Create an instance of SAMMGraph
samm_graph = SAMMGraph()

# Parse the Turtle file to load the graph
samm_graph.parse(model_path)

# Load all model elements from the graph
model_elements = samm_graph.load_model_elements()
```

## 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

units = SammUnitsGraph()

unit_name = "unit:volt"
units.print_info(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_info(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 import SammCli

samm_cli = SammCli()
model_path = "Path_to_the_model/Model.ttl"
samm_cli.validate(model_path)
# Input model is valid
```

List of SAMMCLI functions:
- validate
- prettyprint
- usage
- to_openapi
- to_schema
- to_json
- to_html
- to_png
- to_svg
- to_java
- to_asyncapi
- to_jsonld
- to_sql
- to_aas
- edit_move
- edit_newversion
- aas_to_aspect
- aas_list
- package_import
- package_export

# 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 uv command. uv is available from the folder where [pyproject.toml](pyproject.toml) 
is located.

# Tests running
## 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

### tox-uv plugin

`tox` is integrated with `uv` through the [`tox-uv`](https://github.com/tox-dev/tox-uv) plugin. Both `tox` and 
`tox-uv` are declared as `dev` dependencies in [pyproject.toml](pyproject.toml), so a single `uv sync` installs 
everything required - no separate installation step is needed.

The two environments use the plugin differently (see [tox.ini](tox.ini)):
- `pep8` uses the `uv-venv-lock-runner` provided by `tox-uv`, which provisions the environment directly from the 
  pinned `uv.lock` and installs the `dev` dependency group. This guarantees the linters run with the exact, locked 
  versions.
- `py310` uses the default runner and explicitly runs `uv sync` and `uv run download-samm-release` in its 
  `commands_pre` to prepare dependencies and the SAMM meta model files before executing the test suite.

```console
# run all checks use the next command
uv run tox

# run only pep8 checks
uv run tox -e pep8

# run tests
uv run tox -e py310
```
