Poetry Guider¶

This document provides a guide to understanding Poetry, setting up the project locally, and creating installation packages for the Biofilter project.

What is Poetry?¶

Poetry is a modern dependency management tool for Python projects. It simplifies the process of managing dependencies, creating reproducible environments, and publishing packages. Poetry replaces traditional tools like requirements.txt, setup.py, and virtualenv by consolidating all these functionalities into a single, streamlined workflow.

Why Use Poetry?¶

Simplified Dependency Management: - Define all dependencies in a single pyproject.toml file. - Automatically resolves dependency conflicts and locks exact versions.
Reproducible Environments: - The poetry.lock file ensures consistent environments across different systems.
Built-In Virtual Environment Management: - Poetry handles virtual environments automatically, isolating dependencies.
Integrated Packaging: - Easily create and publish packages to PyPI or distribute locally.

Setting Up the Project Locally¶

Step 1: Install Poetry¶

Follow the official Poetry installation instructions:

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

After installation, verify the installation:

poetry --version

If you’re on Windows, you can use the official installer or refer to the Poetry documentation.

Step 2: Clone the Repository¶

git clone https://github.com/RitchieLab/biofilter.git
cd biofilter

Step 3: Install Project Dependencies¶

Poetry will automatically create a virtual environment and install all dependencies specified in pyproject.toml:

poetry install

Important

Before running poetry install, ensure you are using the desired Python version. This can either be the globally installed Python version or a specific version managed through tools like pyenv. If using pyenv, set the Python version for the project using pyenv local <desired-version> before proceeding with the installation.

Step 4: Activate the Virtual Environment¶

To activate the virtual environment created by Poetry, run:

poetry shell

You can now use the installed dependencies and run project-specific commands within this environment.

Step 5: Run the Project¶

For example, to run one of the entry-point scripts defined in the project:

poetry run biofilter

Creating Installation Packages¶

Step 1: Validate the Project Setup¶

Ensure the pyproject.toml file is properly configured with all required metadata, dependencies, and entry points. Example fields to check: - name - version - description - authors - dependencies - scripts (for entry points like biofilter or loki-build).

Example entry in pyproject.toml:

[tool.poetry.scripts]
biofilter = "biofilter_modules.biofilter:main"
loki-build = "loki_modules.loki_build:main"

Step 2: Build the Package¶

Run the following command to generate distribution files (.tar.gz and .whl) in the dist/ directory:

poetry build

This command will create: - A source distribution (.tar.gz). - A wheel distribution (.whl).

Step 3: Verify the Package¶

To test the installation of the package locally, use:

pip install dist/biofilter-<version>.whl

Replace <version> with the version number of the package.

Step 4: Publish the Package¶

To publish the package to PyPI (or a private repository), use:

poetry publish --build

You will need valid credentials for PyPI or the repository you are targeting. To configure these, run:

poetry config pypi-token.pypi <your-token>

Automating the Workflow¶

You can create a simple script or CI pipeline to automate the steps for building and publishing the package. For example:

#!/bin/bash
# build-and-publish.sh

set -e

echo "Building the Biofilter package..."
poetry build

echo "Publishing the package to PyPI..."
poetry publish --build

echo "Done!"

Make this script executable:

chmod +x build-and-publish.sh

Run it:

./build-and-publish.sh

Managing Dependencies¶

Adding a Dependency¶

To add a new dependency to the project, use:

poetry add <package-name>

Adding a Development Dependency¶

To add a dependency for development purposes (e.g., linters, testing frameworks):

poetry add --group dev <package-name>

Removing a Dependency¶

To remove a dependency from the project:

poetry remove <package-name>

Reproducibility¶

If someone else clones the repository, they only need to run:

poetry install

This command reads the pyproject.toml and poetry.lock files to recreate the exact same environment.