Installation

To be able to communicate with a Mesh server using the Mesh Python SDK some initial setup is needed. Here we suggest one possible setup.

Git

Git is a version control system. To be able to follow along using this guide you will need git to be able to install the Mesh Python SDK.

  1. Download and install:

    • Go to git-scm.com and download the installer.

    • Installation with default settings should suffice.

  2. Configure:

    Git needs to be configured with your name and email address:

    $ git config --global user.name "name"
$ git config --global user.email "email_address"

GitHub

GitHub is a cloud based storage for git repositories. The Mesh Python SDK is hosted on GitHub.

To be able to access the code you will need a GitHub user and that user needs to be given access by Volue.

If you don’t have a GitHub user you can join here.

Python

Mesh Python SDK works with Python 3.9, 3.10, 3.11, and 3.12. Support for earlier and later versions is not provided due to dependencies.

  1. Download and install (Windows):

    1. Go to python.org and download the latest supported release.

    2. Follow installation instructions. Select “Add Python 3.xx to PATH” for easy access on the command line.

    3. For Python installation help refer to official Python documentation.

Development environment

To be able to use the Mesh Python SDK to communicate with a Mesh Server or to do development you will need to write Python code that uses the functionality in the Mesh Python package.

There are many ways to do this, but here we present one of them.

PyCharm

PyCharm is an IDE designed to write and execute Python code.

When working with multiple python projects they may depend on different python versions and/or versions of external libraries. For this purpose, the standard library comes with a concept called Virtual Environments and Packages to help maintain these separate versions.

  1. Download and install:

    1. Go here and download the installer.

    2. Run the installer and follow the steps in the installation wizard.

  2. Create a new project.

  3. Create a python file for your code.

  4. Good to know:

    1. PyCharm Terminal:

      ‘View’ -> ‘Tool Windows’ -> ‘Terminal’ will bring up a command line where the virtual environment is activated.

      Note

      This is the command line where you should run commands for installing new packages. Example: ‘python -m pip install <some_python_package>’.

    2. Execute a script:

      Right click on the <your_python_script>.py in the ‘Project’ view to the right in PyCharm and select ‘Run’.

Mesh Python SDK

Depending on how you intend to use the Mesh Python SDK there are two ways to install it.

If you intend to use it to communicate with a Mesh Server you are a user. If you intend to contribute to development of the SDK you are a developer.

Setup for developers

  1. Clone the repository:

    git clone https://github.com/Volue-Public/energy-mesh-python.git

  2. Install Poetry:

    This library uses Poetry for development, installation and packaging. To work with the repository you should install poetry. The steps below assume Poetry binary is added to your PATH.

    To install all our development and runtime dependencies to a virtual environment go to the Mesh Python SDK repository directory and run:

    poetry install

    To create a package run:

    poetry build

    This will also (re)generate our grpc/protobuf sources, and should be ran after making changes to proto file(s).

    To run arbitrary commands in the Poetry environment run:

    poetry run {command}
# e.g.: poetry run python src\volue\mesh\examples\get_version.py

    Or use:

    poetry shell
# then e.g.: python src\volue\mesh\examples\get_version.py

    to drop into a shell with the dependencies available.

  3. For the development we are using Black auto formatter. It is added as a development dependency and installed automatically by Poetry, so you don’t need to install anything extra. Before committing your changes and creating a Pull Request to Python SDK repository make sure the code is correctly formatted, by running:

    poetry run black .

    Most IDEs have options to automate the usage of auto formatters like Black, e.g.: the formatting can be executed on file save, so you don’t need to make an explicit call like presented above.

Tests

There are different types of tests. Some tests require running Mesh server instance with specific test model named: SimpleThermalTestModel. Such tests are marked with database. Other types like unittest do not require Mesh server at all. To see all types of tests see markers in [tool.pytest.ini_options] section in pyproject.toml file.

Pytest allows you to specify which tests to run. For example, to check all tests except authentication and long tests:

poetry run pytest -m "not authentication and not long"

When submitting a new Pull Request the tests are run automatically using GitHub Actions.

Dependencies

The Mesh Python SDK depends on the Python standard library, but also gRPC and Apache Arrow.

These dependencies are managed, installed and referenced by the library using Poetry. No additional dependencies should be needed after running the pip install.