.. _poetry:

Poetry 
======

Poetry è un sistema di gestione pacchetti analogo a ``pip`` ma con alcune
differenze:

* è basato su un formato di specifiche del  pacchetto chiamato ``pyproject.toml``
  che dovrebbe soppiantare ``setup.py``

* ha una gestione delle dipendenza molto più simile a ``yarn`` (js):

  + si aggiungono pacchetti con ``poetry add`` e questo mette già la dipendenza
    nel file di configurazione. Per ``pip`` occorre ricordarsi di aggiungere a mano
    ed è causa di tanti errori

  + la creazione dell'ambiene virtuale di ottiene con ``poetry install``

  + ha un suo file di ``poetry.lock`` che descrive esattamente cosa è
    installato. Attenzione che deve essere presente per installare altri
    pacchetti.

* quando disinstallo un pacchetto, anche le sue dipendenze vengono disinstallate

* permette di vedere l'installato tramite il comando ``poetry show`` che ha una
  opzione ``-t`` che mostra tutto l'albero delle dipendenze.


.. note::
   L'ambiente virtuale può essere generato come volete (virtualenvwrapper o
   python -m venv mio-evn ma è necessario che poi pip sia almento alla versioen
   20 quindi suggerisco::

     poetry run pip install --upgrade pip

.. note::
   Non mescolate un env fatto con poetry ed uno fatto con pip. Pip non scrive le
   informazioni necessarie a poetry.

Per installarlo occorre:

  curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py|python


pyproject.toml
---------------

Com anticipato sopra, il file di configurazione usato da ``poetry`` è
``pyproject.toml``, il formato definito nella `PEP 518`_.

Sostanzialmente, fino ad ora non era possibile avere certezza di quali strumenti
fossero necessari per costruire un pacchetto e setuptools e wheele venivano
messi in ogni virtualenv solo "tentativamente".

Ora questo sta scritto in chiaro in una sezione, ad esempio per poetry::

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

mentre per setuptools::

  [build-system]
  requires = ["setuptools >= 40.6.0", "wheel"]
  build-backend = "setuptools.build_meta"

Letture suggerite
------------------

Ecco alcuni suggerimenti di lettura per approfondire l'argomento:

* `PEP 518`_: Specifying Minimum Build System Requirements for Python Projects -
  State: final

* `PEP 517`_: A build-system independent format for source trees - State: provisonal

* `What the heck is pyproject.toml?`_ di Brett Cannon



.. _`PEP 518`: https://www.python.org/dev/peps/pep-0518/
.. _`PEP 517`: https://www.python.org/dev/peps/pep-0517/
.. _`What the heck is pyproject.toml?`: https://snarky.ca/what-the-heck-is-pyproject-toml/