Setting Up a Development Environment#

If you have access to the internal LASP confluence space, please refer to the following resources:

Managing Multiple Base Python Versions#

In order to develop with multiple different versions of Python and create virtual environments associated with different versions of Python, you will need multiple base Python interpreters. There are several ways to manage this including Conda, PyEnv, and building Python from source. We recommended using Conda and outline the steps below for using Conda to manage multiple base Python installations.

  1. Install miniconda according to the official documentation. If you already have miniconda or anaconda installed, you can skip this step.

  2. Optionally run conda config --set auto_activate_base false to add a configuration to your .condarc file to disable auto-activation of the base conda environment on shell startup.

  3. Create a conda environment with your preferred version of python: conda create -n conda-python3.11 python=3.11

    • Note: Name this environment with a convention that makes sense to you for a base interpreter. Do not delete this conda environment! Deleting it will break all subsequent virtual environments based on it.

  4. The Python interpreter provided by your new conda environment is a full base interpreter and you can use it to create virtual environments. You can find the full path to the base interpreter by running something similar to the following (run conda env list to see why this works):

    PATH_TO_PYTHON=$(conda env list | grep "conda-python3.11" | awk '{print $2}')/bin/python
$PATH_TO_PYTHON -m venv path/to/new/venv

Installing Poetry#

Poetry is a command line tool that helps manage a python development environment, including package management, virtual environment management, and package building.

Poetry official installation instructions can be found here: https://python-poetry.org/docs/#installation

To ensure that Poetry is always available and in the PATH it is recommended to install Poetry with your pre-installed system python interpreter rather than as a package in a conda environment or in a virtual environment. The specific version of python with which you install Poetry is inconsequential (as long as it is currently supported by Poetry). If your system python is not supported by Poetry, you can install Poetry in your conda base environment. Just remember that Poetry will only be available when that environment is activated. Things can get a bit confusing when you have a conda environment active and a derived virtual environment activated on top of it.

Once poetry is installed, check that it works by running poetry --version. You should get something like

Poetry version 1.4.0

Installing Poetry with System Python#

Ensure that all your virtual environments and conda environments are deactivated and that which python3 refers to your system python interpreter (usually /usr/bin/python3).

curl -sSL https://install.python-poetry.org | python3 -

Installing Poetry in the Conda base Environment#

conda activate
conda install -y poetry
poetry --version
conda deactivate
poetry --version  # This should fail to find Poetry

Configuring Poetry#

We recommend configuring Poetry to create virtual environments in project directories by default.

poetry config virtualenvs.in-project true

This command will write a value to a config file for your global poetry installation. On Mac this is in ~/Library/Application\ Support/pypoetry/config.toml.

Setting Up Development Virtual Environment(s)#

Poetry manages virtual environments for you on a per-package and per-python-version basis. However, Poetry will dynamically detect the presence of an activated virtual environment and use that if present.

  1. Deactivate all Conda environments and virtual environments (except for the conda environment which contains Poetry, if applicable).

  2. Save the path to the version of Python you want to use for development

    PATH_TO_PYTHON=$(conda env list | grep "conda-python3.11" | awk '{print $2}')/bin/python

  3. Instruct Poetry to create a managed virtual environment

    poetry env use $PATH_TO_PYTHON

    This will create a virtual environment. If you have enabled virtualenvs.in-project as described above, it will be created in your project directory in .venv.

  4. Configure your IDE to recognize the correct poetry-managed virtual environment for the version you wish to develop with.

  5. Run poetry env info and verify that Poetry is recognizing your virtual environment properly:

    Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           /Users/myuser/path/to/libera_utils/venv
Valid:          True

Changing Python Versions#

It is common to recreate your virtual environment on a regular basis in order to use different python versions. You can do this with

poetry env use /full/path/to/python

Poetry will recreate your virtual environment in the .venv directory if virtualenvs.in-project is set. Otherwise it will create a virtual environment in ~/Library/Caches/pypoetry/virtualenvs.

Installing Dependencies#

  1. Run poetry install in the same directory as the pyproject.toml file. You should see poetry solving the dependency tree and then installing dependencies. This also installs dev group dependencies, as specified in pyproject.toml. Lastly you should see it installing the local package.

  2. To install optional “extra” dependencies, run poetry install -E extra_name1 -E extra_name2. These extra dependencies are specified in pyproject.toml under [tool.poetry.extras]. Note that any subsequent poetry install command without --extras will implicitly uninstall any previously installed extras.

  3. To install dependency “groups” (think labels), which may or may not be optional, use the --with and --without flags for Poetry. e.g. poetry install --with docgen will install the dependencies for the optional group “docgen”.

  4. Verify that the libera_utils package was installed correctly by running libera-utils --version. This runs the libera-utils command line utility that is included in the package. This can also be run with poetry run libera-utils --version.

  5. Next, go run the tests.

On this page
Show Source