Eclipse uProtocol Python Library

Table of Contents

• Overview
• Getting Started
  • Prerequisites
  • Importing the Library
  • Using the Library
  • Cleaning Up
  • Running the Tests
  • Generate coverage report

Overview

This library implements the uProtocol Language Specific Library Requirements for Python defined in uProtocol Specifications. The library is organized into packages that are described in SDK Packages below and organized by the layers of the protocol.

Each package contains a README.adoc file that describes the purpose of the package and how to use it.

The module contains the factory methods, serializers, and validators for all data types defined in the specifications, and any data models that either haven’t or couldn’t be defined in uprotocol-core-api yet (ex. UPayload) This library fits into the big picture of the uProtocol SDK as seen in the diagram below.

uProtocol SDK

Getting Started

Prerequisites

Before proceeding with the setup of this project, ensure that the following prerequisites are met:

• git is installed and configured in your environment.

• Python 3.8+ is installed and configured in your environment.

Importing the Library

To set up SDK, follow the steps below:

1. Clone the code from the GitHub repository , The repository contains the reference to up-spec main branch as the git submodule:

   git clone --recurse-submodules https://github.com/eclipse-uprotocol/up-python.git
   cd up-python

   If you have already cloned without --recurse-submodules, you can initialize and update using:

   git submodule update --init --recursive

2. Generate Python proto bindings using the provided script:

   python generate_proto.py

   This script will compile the up-spec protos locally and generate Python proto files under the appropriate package folders for local use in your environment.

3. Install up-python

   python -m pip install ../

This will install up-python, making its classes and modules available for import in your python code.

Using the Library

The Library is broken up into different packages that are described in SDK Packages below. Each package contains a README.adoc file that describes the purpose of the package and how to use it. Packages are organized into the following directories:

Table 1. SDK Packages

Package	Protocol Layer	Purpose
client	Application Layer (uP-L3)	Top level client-facing interfaces to communication with USubscription, UDiscovery, and UTwin services.
communication	communication layer (uP-L2)	Common implementation of communication messaging patterns (publisher, subscriber, Rpcclient, RpcServer, etc..) that is build on top of the L1 transport interface (see below)
transport	Transport Layer (uP-L1)	Interface and data model for how to send() and receive() messages in a common way across various transport technologies (ex. zenoh, mqtt, http, etc…​). the interface is implemented by transports (ex. up-transport-zenoh-python), and the interface is then used to build the uProtocol layer 2 communication layer implementation.
uri		Uniform Resource Identifier (RFC3986), how uProtocol addresses things (devices, software, methods, topics, etc…​) on the network.
uuid		Identifier used to uniquely identify (and timestamp) messages that are sent.

Note	Please visit the READMEs in SDK Packages for examples of how to use the different data types and their factories, validators, and serializers.

Cleaning Up

Clean up by running the command: python clean_project.py

Running the Tests

• Execute below command from up-python directory

python -m coverage run --source uprotocol/ -m pytest

Generate coverage report

python -m coverage report
python -m coverage html

This generates the HTML report to htmlcov\index.html