Manage dependencies with Poetry

This page contains instructions for managing the pittgoogle-client package dependencies using Poetry. Poetry was implemented in this repo in pull #7.

Setup your environment

Create a new conda environment for poetry and install it (Poetry installation). If you already did this, just activate the environment.

conda create --name poetry-py312 'python=3.12'
conda activate poetry-py312

# pipx is recommended, but it requires a brew install on MacOS and I (Raen) avoid brew whenever possible.
# pip seems to work fine.
pip install --upgrade poetry

Install existing dependencies

This repo already contains a poetry.lock file, so running poetry install will give you the exact versions specified there (Poetry install dependencies).

poetry install

If you want to install the docs and tests dependencies as well, use:

poetry install --with docs,tests

Add a Dependency

Use poetry add and then poetry update (Poetry add dependencies; see also: Poetry version-constraint syntax). Here are examples:

# This example adds pandas to the main dependencies.
poetry add pandas

# This example adds sphinx to the docs dependencies.
poetry add sphinx --group docs.dependencies

# Resolve all dependencies and update to latest compatible versions.
poetry update

Now commit the updated pyproject.toml and poetry.lock files to the repo.

Update Dependency Versions

To upgrade to the latest versions compatible with the pyproject.toml file, you have two options below (Poetry update dependencies):

Option 1: Simple update using existing environment and lock file

# This will start from the existing environment and poetry.lock file and update from there.
poetry update

Now commit the updated poetry.lock file to the repo.

Option 2: Clean start and full update

# --------- Optional Setup --------- #
# Recreate the conda environment named 'poetry-py312'. Be sure to deactivate the environment first.
conda remove --name poetry-py312 --all
conda create --name poetry-py312 'python=3.12'
conda activate poetry-py312
pip install --upgrade poetry
# ---------------------------------- #

# Delete the lock file and rebuild
rm poetry.lock
poetry install --with docs,tests

Now commit the updated poetry.lock file to the repo.