# Master your working environment using poetry

There are lots of environment management systems out in the wild, one of my favorites in **poetry**.

Below a non exhautive list of available environement managers:
|Tool| [Poetry](https://github.com/python-poetry/poetry) | [Pipenv](https://pipenv.pypa.io/en/latest/) | [Conda](https://github.com/conda/conda) | [Pipx](https://github.com/pypa/pipx)
|-------- | -------- | -------- | -------- |-------- |
| Github Stars| 24.4k | 23.7k| 5.3k | 6.2k|

## Let's dive into poetry

Poetry helps you declare, manage and install dependencies of Python projects, ensuring you have the right stack everywhere. Upon any new dependencies you will be adding to your environment, poetry will check the possible conflicts with other packages and install all the dependencies related to your new addition.

### 1- Setup poetry:
I prefer to use conda in order to have control on the python version that will be later used by poetry.

In your working directory, start by creating a minimal conda environment using a configuration file

> vi environment.yaml

name: demo
channels:
  - default
  - conda-forge
dependencies:
  - python=3.9
  
 > conda env create -f environment.yaml
 > conda activate demo

Then install your preferred poetry version:

> curl -sSL https://install.python-poetry.org | python3 -
> poetry --version
    Poetry version 1.4.1

You can also check the official documentation for further specifications like installing a specific version of poetry.

### 2- Configure your working environment using poetry:
Poetry provides a CLI for setting up an environment, you can simpli launch below command & answer a couple of questions which will then bootstrap the `pyproject.toml` file for you.

(demo) user@IT-95 poetry_demo % poetry init

This command will guide you through creating your pyproject.toml config.

Package name [poetry_helper]:  demo-poetry
Version [0.1.0]:
Description []:  a demo for poetry env handler
Author [xxxyyy <[e-mail]>, n to skip]:  Demo User <[e-mail]>
License []:
Compatible Python versions [^3.9]:

Would you like to define your main dependencies interactively? (yes/no) [yes] n
[tool.poetry]
Would you like to define your development dependencies interactively? (yes/no) [
yes] no

Below an example of `pyproject.toml` file

[tool.poetry]
name = "demo-poetry"
version = "0.1.0"
description = "a demo for poetry env handler"
authors = ["Demo User <[e-mail]>"]

[tool.poetry.dependencies]
python = "^3.9"

[tool.poetry.dev-dependencies]

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Do you confirm generation? (yes/no) [yes] ys
This will create automatically the pyproject.toml file in which to find your production & development environments
[tool.poetry]
name = "demo"
version = "0.1.0"
description = "a demo for poetry env handler"
authors = ["Demo User <[e-mail]>"]
[tool.poetry.dependencies]
python = "^3.9"
[tool.poetry.dev-dependencies]
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

---
On of the good practices is to also adapt the poetry configuration to your needs, this is useful for example when you want to write your virtual environment dependencies next to your project.

You can add a poetry.toml file in which you specify to register your env dependencies in current folder

>>> poetry.toml
[virtualenvs]
in-project = true

You folder final folder hierarchy should be as such

/my-project
    pyproject.toml
    poetry.toml
    /my-project  # folder to contain your code sources
    Dockerfile   # (Optional)

Next you just need to launch `poetry install` command, this will create your virtual environment & setup all specified dependencies in `pyproject.toml` file.
Your new folder hierarchy will look like this:

/my-project
    pyproject.toml
    poetry.toml
    poetry.lock
    ./venv
    /my-project  # folder to contain your code sources
    Dockerfile   # (Optional)

A new file has been automatically generated `poetry.lock` is used by poetry to accelerate the install time by avoiding launching the dependencies resolve each time.

### 3 - Add a customized dependencies

Once your poetry management is well setup, you can easily add new packages either through command line or by editing the `pyproject.toml` directly.

PS: when modifying the `pyproject.toml` you need to launch `poetry update` in order to make sure your `poetry.lock` is well synchronized.

You can easily add a new package using :

poetry add numpy pandas=1.5.3 matplotlib = "^3.7.1"

You can also add packages with a small specification that they belong to development-dependencies

poetry add -D black pytest

You can remove a package using 

poetry remove <my-package>

### 4 - Add a private packages repository

> poetry config repositories.jfrog <path-to-jfrog-repo> && \
> poetry config http-basic.jfrog "${POETRY_HTTP_BASIC_USERNAME}" "${POETRY_HTTP_BASIC_PASSWORD}"

### Activating your virtual environment
You can use `poetry shell` to activate your virtual env

> poetry shell
> (demo-poetry) python -m my-script

Or launch python with poetry support

> poetry run -m python -m my-script

# TODO
## Handle migration from pip to poetry & vice versa