⚠️ On 2021-11-15, this project replaced a legacy Python implementation of SiLA 2. That project can be found here and is still installable via pip install sila2lib.

SiLA 2 Python Implementation

Getting started

Installation

Use pip install sila2 to install the latest release of the library.

There are optional dependencies:

• pip install sila2[codegen] is required for code generation but not for running SiLA Servers or Clients
• pip install sila2[cryptography] is required for auto-generating self-signed SSL certificates on server startup, and for additional certificate validation steps by the client

On Raspberry Pi systems, run the following to fix some ImportErrors:

• pip uninstall -y lxml grpcio grpcio-tools
• sudo apt install -y python3-lxml python3-grpcio python3-grpc-tools

Dependencies

This project only has a few direct dependencies:

• grpc for gRPC-based communication
• lxml for XML interactions (parsing, XSD validation, XSL transformation)
• zeroconf for SiLA2 Server Discovery
• typing-extensions for type hinting
• typer for server command line interfaces (server only, can be disabled during code generation)

A list of all dependencies (including transitive dependencies) for the latest version of the example server can be found here

Documentation

A documentation on SiLA Server generation, feature implementation, and usage of SiLA Clients can be found here.

Example

The directory example_server contains an example SiLA Server application. example_client_scripts contains multiple SiLA Client programs that interact with the example server.

Implementation status

Missing parts from SiLA 2 specification

• Lifetime handling for binary transfer
  • currently, large binaries are only deleted on request
• Server-initiated connection (SiLA 2 v1.1)
  • currently, only client-initiated connections are supported

Deviations from SiLA 2 specification

• Duration is rounded to microseconds, because datetime.timedelta does not support sub-microsecond precision
• Microseconds of datetime.time and datetime.datetime are ignored since Time and Timestamp don't support sub-second precision

Contributing

Contributions in the form of issues, feature requests and merge requests are welcome. To reduce duplicate work, please create an issue and state that you are working on it before you spend significant time on writing code for a merge request.

Development

Multi-stage build process

Because the sila2.features submodule is auto-generated using the code generator included in this library, the build process has multiple steps:

1. Install the library without sila2.feature
2. Use the script generate-feature-submodule.py to generate sila2.feature
3. Install again

Development tools

This project uses the following tools to improve code quality:

• ruff for code formatting and linting
• pytest for testing
• pytest-cov for measuring code coverage

The following Python scripts are provided to guide the development process:

• run-formatting.py applies ruff format and ruff check --select I --fix .
• run-checks.py checks for formatting and code style problems, and runs the tests
• install-pre-commit-hook.py installs a pre-commit git hook to automatically execute a fast-running subset of all checks on each commit

To install all these tools, use pip install .[dev].

Documentation build process

To build the documentation, first install this library with pip install .[docs], the run docs/make-docs.py. The HTML documentation can then be found at docs/_build/html

Setup code

The full development setup using the setuptools development mode looks like this:

# clone repository
git clone --recurse-submodules https://gitlab.com/sila2/sila_python
cd sila2

# install sila2 in development mode
pip install -e .[full]  # install without sila2.feature submodule and all optional dependencies
python generate-feature-submodule.py  # generate sila2.feature code (generates src/sila2/feature/...)

# build documentation (generates docs/_build/html)
python docs/make-docs.py

# install example server in development mode (required for tests)
pip install -e example_server

# run test suite
python run-checks.py

# run code formatting
python run-formatting.py

# install git pre-commit hook (generates .git/hooks/pre-commit)
python install-pre-commit-hook.py

# build wheel and source distribution (generates build/ and dist/)
pip install build
python -m build -ws