Python Environment

Mavkit uses Python to build this documentation website (https://protocol.mavryk.org) and for a limited set of utility scripts (although this latter usage of Python is deprecated). This page contains installation instructions for the Python environment.

Installation

Prerequisites:

  • python 3.11.8. It is recommended to use pyenv to manage the python versions. If you want to use pyenv:

    • Follow the installation instructions. In particular, this ensures that eval "$(pyenv init -)" has been executed first during the shell session, by adding this line to an environment script sourced automatically.

    • You can use then pyenv install 3.11.8, followed by:

      • pyenv local 3.11.8 to use python 3.11.8 only in the current directory (and its subdirectories, unless redefined)

      • pyenv global 3.11.8 to set the python version to 3.11.8 globally

      • pyenv shell 3.11.8 to use python 3.11.8 only in the current shell

  • poetry 1.2.2 to manage the python dependencies and run the tests in a sandboxed python environment. Follow the installation instructions.

    Before using the python environment for the first time, the dependencies must be installed. To achieve this, run poetry install in the root of the project.

A typical installation of the above prerequisites (including their own prerequisites) proceeds as follows, see below for full details:

# 1. install pyenv
# 2. restart shell, to ensure "pyenv init -" has been evaluated
# 3. then install python using pyenv:
pyenv install 3.11.8
pyenv global 3.11.8
# 4. install poetry
# 5. restart shell, to activate the poetry setup
# 6. then install dependencies for Mavkit using poetry:
cd tezos/
poetry install

Installation details for Ubuntu 20.04

First, make sure curl and git are installed, as they are required by the pyenv and poetry installers:

sudo apt-get install curl git --yes

For pyenv to compile Python, you’ll have to install python’s build dependencies:

sudo apt-get install make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev --yes

Now, install pyenv using pyenv-installer:

curl https://pyenv.run | bash

To make pyenv available in your shell session, add the following to your shell configuration file, e.g. ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.pyenv/bin:$PATH" # add pyenv to path
eval "$(pyenv init --path)"          # adds pyenv plugins to path
eval "$(pyenv init -)"               # adds pyenv setup to environment
eval "$(pyenv virtualenv-init -)"    # adds virtualenv setup to environment

To verify the pyenv installation, restart your terminal and try executing pyenv:

pyenv --version

Now we can use pyenv to install Python 3.11.8 and set it as the default version:

pyenv install 3.11.8
pyenv global 3.11.8

Now verify that the correct version is called when running python:

python --version # should output 3.11.8

Now, on to installing poetry. We’ll use poetry’s official installer:

curl -sSL https://install.python-poetry.org -o install-poetry.py
python install-poetry.py --version 1.2.2 --yes

As for pyenv, we need to do some shell setup to put poetry in the shells path. Add the following to your shell configuration file, e.g. ~/.bashrc or ~/.zshrc:

export PATH=$PATH:$HOME/.local/bin

Restart the terminal and verify that the correct version is called when running poetry:

poetry --version # should output 1.2.2

Finally, let’s use poetry to install the python dependencies of Mavkit. This command needs to run in the root of the Mavkit checkout:

cd mavryk
poetry install

If the installation went well, you should now have the correct version when executing poetry in the Mavkit checkout for our main dependency (sphinx-build for documentation):

poetry run sphinx-build --version # should output 4.2.0

Adding new dependencies

Dependencies are managed by poetry in the file pyproject.toml. See the reference for the pyproject.toml files. The file poetry.lock is generated by running poetry lock, and must never be changed manually. The resulting poetry.lock and its generator pyproject.toml must be copied in this repository.