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 either pip or uv. The remainder of the guide assumes usage of uv. Please refer to the pip installation or uv installation guide. You can check your installed pip/uv version with
```
pip --version
```
or

uv --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. These methods allow you to read a Turtle file, parse 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:

pip install 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 a specific version of the package, you can use the following command:

pip install esmf-aspect-model-loader==<version>

Replace <version> with the desired release; the available versions are listed on PyPI.

For more detailed information how to install a library with pip please read pip Installing Packages guide.

uv

To install the esmf-aspect-model-loader with the uv dependency manager, you can use the following command:

uv 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 a specific version of the package, you can use the following command:

uv add esmf-aspect-model-loader==<version>

Replace <version> with the desired release; the available versions are listed on PyPI.

For more detailed information how to add a library via uv please read uv dependencies guide.

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

Consuming an Aspect via its JSON payload

The Aspect Model Editor can export an example JSON payload for an Aspect via its Export JSON function. For the Movement Aspect the payload looks as follows:

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

The example below shows how to load the Aspect Model with the Aspect Model Loader and expose the payload values through a small wrapper class.

import json
import requests

from esmf_aspect_meta_model_python import SAMMGraph


class MovementAspect:
    def __init__(self, path_to_turtle_file):
        self._ttl_file_path = path_to_turtle_file

        # Parse the Turtle file and load the Aspect model.
        samm_graph = SAMMGraph()
        samm_graph.parse(self._ttl_file_path)
        self._aspect = samm_graph.load_aspect_model()
        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.