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?
---------------

1. **Simplified Dependency Management**:
   - Define all dependencies in a single ``pyproject.toml`` file.
   - Automatically resolves dependency conflicts and locks exact versions.

2. **Reproducible Environments**:
   - The ``poetry.lock`` file ensures consistent environments across different systems.

3. **Built-In Virtual Environment Management**:
   - Poetry handles virtual environments automatically, isolating dependencies.

4. **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:

.. code-block:: bash

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

After installation, verify the installation:

.. code-block:: bash

   poetry --version

If you're on Windows, you can use the official installer or refer to the `Poetry documentation <https://python-poetry.org/docs/>`_.

Step 2: Clone the Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   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``:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   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``:

.. code-block:: 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:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   poetry publish --build

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

.. code-block:: bash

   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:

.. code-block:: bash

   #!/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:

.. code-block:: bash

   chmod +x build-and-publish.sh

Run it:

.. code-block:: bash

   ./build-and-publish.sh

Managing Dependencies
----------------------

Adding a Dependency
~~~~~~~~~~~~~~~~~~~

To add a new dependency to the project, use:

.. code-block:: bash

   poetry add <package-name>

Adding a Development Dependency
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: bash

   poetry add --group dev <package-name>

Removing a Dependency
~~~~~~~~~~~~~~~~~~~~~

To remove a dependency from the project:

.. code-block:: bash

   poetry remove <package-name>


Reproducibility
---------------

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

.. code-block:: bash

   poetry install

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

Additional Resources
--------------------

- `Official Poetry Documentation <https://python-poetry.org/docs/>`_
- `FAQ and Troubleshooting <https://python-poetry.org/docs/faq/>`_