ESMF SDK Python Aspect Model Loader

The Python SDK offers functionality which helps software developers to work with Aspect Models in their Python applications.

This guide gives an overview of the components in the Python SDK and shows how to use them.

Getting Started

Prerequisites

Python Version 3.10 or higher. Check your version with
```
python --version
```
In order to include the packages a Python dependency manager is required; we recommend Python Poetry. The remainder of the guide assumes usage of Poetry. Please refer to the Poetry installation guide. You can check your installed Poetry version with
```
poetry --version
```

Aspect Model Loader for Python

Introduction

Aspect Models are stored as RDF Graphs in .ttl (RDF Turtle) files. The Aspect Model Loader for Python offers a SAMMGraph class that provides two main methods: load_aspect_model and load_model_elements. Theese methods allows to read a Turtle file and parses the Aspect Model and return either a root Aspect node or a list of all elements from the Aspect Model. The Aspect has references to all of its children (e.g., Properties and Operations).

Installation

If you want to work with Aspect Models in your Python solution you should install the Aspect Model Loader for Python and include it into your project.

Installation from package Repository

PyPI

To install the esmf-aspect-model-loader from PyPI, you can use the following command:

poetry add esmf-aspect-model-loader

You can specify the version of the package by adding the version number after the package name. For example, to install version 2.2.0 of the package, you can use the following command:

poetry add esmf-aspect-model-loader==2.2.0

For more detailed information how to add a library via poetry please read Poetry add guide.

GitHub Releases

To use GitHub release as dependency using Poetry, you need to add it like this:

[tool.poetry.dependencies]
esmf-aspect-model-loader = { git = "https://github.com/eclipse-esmf/esmf-sdk-py-aspect-model-loader.git", tag = "v2.2.0", subdirectory = "core/esmf-aspect-meta-model-python" }`

for more information on depend on a library located in a git: git dependencies

Installation with local package

The Python package is an archive with the file ending .tar.gz. If you are working with Poetry, you can easily import that package by adding the local reference to your pyproject.toml

[tool.poetry.dependencies]
esmf-aspect-model-loader = { path = "path/to/esmf-aspect-meta-model-python-x.y.z.tar.gz" }

To make Poetry recognize your changes, run

poetry update

Loading an Aspect Model

Note: The examples below will be using the Movement.ttl Aspect model.

Loading an Aspect Model

# import a SAMMGraph class to your Python module
from esmf_aspect_meta_model_python import SAMMGraph

# Define the path to local Turtle file
model_path = "PATH_TO_TURTLE_FILE"

# 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()
print(aspect)

# or load all model elements
elements = samm_graph.load_model_elements()
for element in elements:
    print(element)

where the input argument PATH_TO_TURTLE_FILE can either be a Path object or a string representing a path to the ttl file. Both, relative paths and absolute paths are allowed.

Traversing the Aspect Model

The attributes of an Aspect can be accessed with like this:

name = aspect.name
urn = aspect.urn
preferred_names = aspect.preferred_names
descriptions = aspect.descriptions
meta_model_version = aspect.meta_model_version
see = aspect.see

properties = aspect.properties
operations = aspect.operations
events = aspect.events

Implementation of the OpenAPI specification

The Aspect Models Editor provides easy ways to generate an example for an interface via Export JSON functions. Based on its structure, you can prepare either a server to send data, or a client to receive via the API.

{
  "isMoving": true,
  "position": {
    "altitude": 153,
    "latitude": 9.1781,
    "longitude": 48.80835
  },
  "speed": 0,
  "speedLimitWarning": "green"
}

A simple example of the server

import random


def generate_random_float():
    """Generate a random float value."""
    return round(random.random(), random.randint(0, 5))

def send_movement_value():
    """A simple snippet to generate Movement data."""
    traffic_lights = ["green", "yellow", "red"]
    movement = {
        "isMoving": "true" if random.randint(0, 1) else "false",
        "position": {
            "altitude": generate_random_float(),
            "latitude": generate_random_float(),
            "longitude": generate_random_float()
        },
        "speed": generate_random_float(),
        "speedLimitWarning": traffic_lights[random.randint(0, len(traffic_lights) - 1)]
    }

    return movement

Consumer Example

import json
import requests

def get_movement(url, method="get"):
    """Get a movement."""
    response = requests.request(method, url)

    if response.status_code != 200:
        raise Exception(response.text)
    else:
        movement = json.loads(response.text)

        return movement

Example of the class for Movement Aspect Model

import json
import requests

from esmf_aspect_meta_model_python.loader.aspect_loader import AspectLoader

loader = AspectLoader()

class MovementAspect:
    def __init__(self, path_to_turtle_file):
        self._ttl_file_path = path_to_turtle_file
        self._aspect = loader.load_aspect_model(self._ttl_file_path)
        self._movement = None

        self.name = None
        self.urn = None
        self.preferred_names = None
        self.descriptions = None
        self.meta_model_version = None
        self.see = None
        self.properties = None
        self.operations = None
        self.events = None


        self._init_aspect()

    def _init_aspect(self):
        self.name = self._aspect.name
        self.urn = self._aspect.urn
        self.preferred_names = self._aspect.preferred_names
        self.descriptions = self._aspect.descriptions
        self.meta_model_version = self._aspect.meta_model_version
        self.see = self._aspect.see

        self.properties = self._aspect.properties
        self.operations = self._aspect.operations
        self.events = self._aspect.events

        self._movement = self._get_current_value()

    @staticmethod
    def _get_current_value():
        response = requests.request("get", "url_to_movement_API")

        if response.status_code != 200:
            raise Exception(response.text)
        else:
            movement = json.loads(response.text)

            return movement

    def refresh_data(self):
        self._movement = self._get_current_value()

    @property
    def is_moving(self):
        return self._movement["isMoving"]

    @property
    def position(self):
        return self._movement["position"]

    @property
    def speed(self):
        return self._movement["speed"]

    @property
    def speed_limit_warning(self):
        return self._movement["speedLimitWarning"]


# Class usage
movement = MovementAspect("path_to_turtle_file")
# Get a movement values
print(movement.is_moving)
print(movement.position)
print(movement.speed)
print(movement.speed_limit_warning)
# Show static aspect data
print(movement.name)
print(movement.urn)
print(movement.preferred_names)
print(movement.descriptions)
print(movement.meta_model_version)
print(movement.see)
print(movement.properties)
print(movement.operations)
print(movement.events)

Note that the attributes on Aspect Model objects are read-only.

SAMM Aspect Meta Model in Python

Introduction

The SAMM Aspect Meta Model is defined by multiple Turtle files in the public ESMF GitHub Repository. The project is developed in Java and the releases are published as JAR files.

Python applications that work with Aspect Models and RDF may need the SAMM as a Python package. Therefore, the project SAMM Aspect Meta Model for Python was created. It is set up to extract the RDF Turtle files from the released SAMM artifact or its Github repository and pack them into a Python project.

If you are not sure whether you need the SAMM Aspect Meta Model as a dependency you probably don’t need it because it does not contain any Python functionality. It is only intended for working with Aspect Models on RDF level.