up-python 0.1.2.dev0

Language specific uProtocol library for building and using UUri, UUID, UAttributes, UTransport, and more.

= Eclipse uProtocol Python Library
:toc:

== Overview

This library implements the https://github.com/eclipse-uprotocol/uprotocol-spec/blob/main/languages.adoc[uProtocol Language Specific Library Requirements] for Python defined in https://github.com/eclipse-uprotocol/uprotocol-spec/tree/main[uProtocol Specifications]. The library is organized into 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.

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 <<uprotocol-sdk>> below.

.uProtocol SDK
image:https://raw.githubusercontent.com/eclipse-uprotocol/uprotocol-spec/main/uprotocol_sdk.drawio.svg[#uprotocol-sdk,width=100%,align="center"]


== Getting Started

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

* Maven is installed and configured in your environment. You can verify this by running the following command in your terminal:
[,bash]
----
mvn -version
----
If Maven is properly installed, you should see information about the Maven version and configuration.

=== Importing the sdk

To set up SDK, follow the steps below:

. Clone the code from the GitHub repository:
+
[source]
----
git clone https://github.com/eclipse-uprotocol/uprotocol-python.git
----

. Execute the `pull_and_compile_protos.py` script using the following command:
+
[source]
----
python pull_and_compile_protos.py
----
This script automates the following tasks:

1. **Cloning and Compilation of Protos:**
   Clones the `up-core-api` protos from the specified repository URL, compiles them, and generates Python protofiles in the protos folder.

. Install up-python
+
[source]
----
python -m pip install .
----

*This will install the 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:

.Package Folders
[#pkg-folders,width=100%,cols="20%,80%",options="header"]
|===

| Folder | Purpose

| `*builder*` or `*factory*`
| Contains factory methods for creating uProtocol data types

| `*serializer*`
| Contains serializers to convert the objects into byte or string form representation of said object

| `*validator*`
| Contains validators to validate the data types and report errors if the objects are missing or incorrect

|===


.SDK Packages
[#sdk-packages,width=100%,cols="20%,80%",options="header"]
|===

| Package | Purpose

| link:uprotocol/uri/README.adoc[`*uuri*`]
| Uniform Resource Identifier (RFC3986), how uProtocol addresses things (devices, software, methods, topics, etc...) on the network

| link:uprotocol/uuid/README.adoc[`*uuid*`]
| Identifier used to uniquely identify (and timestamp) messages that are sent

| link:uprotocol/rpc/README.adoc[`*rpc*`]
| Interface to build client and service stubs for uServices. This interface is then implemented by https://github.com/eclipse-uprotocol/uprotocol-spec/blob/main/up-l2/rpcclient.adoc[RpcClient interface]

| link:uprotocol/transport/README.adoc[`*utransport*`]
| Interface and data model declaration used for bidirectional point-2-point communication between uEs. This interface is then implemented by https://github.com/eclipse-uprotocol/uprotocol-spec/blob/main/ulink.adoc[ulink] libraries for a given underlining transport (ex. Binder, MQTT, Zenoh, SOME/IP, DDS, HTTP, etc…​)

| link:uprotocol/cloudevent/README.adoc[`*cloudevent*`]
| Common way to represent uProtocol messages using CloudEvent data model used by some transports (ex. MQTT, HTTP, etc…​)

|===

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

Requires coverage to be installed first, that can be done by running `pip install coverage`

then you run:
`python -m coverage run --source tests/ -m unittest discover`