<type>documentation</type>
<domain>packages</domain>
<id>poetry</id>
<title>Package Management with Poetry</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

When `Poetry <https://python-poetry.org/>`__ is used for package management, Wing
runs ``poetry`` command lines to implement the package operations.  

Configuring Python Executable
-----------------------------

When using Poetry, the ``Python Executable`` in Wing's ``Propect Properties`` should be
set to the virtualenv created by Poetry. Wing checks the configuration and asks to correct
the ``Python Executable`` if necessary. If this is not done, Wing will debug and execute
your code in the wrong Python environment.

You may elect to correct ``Python Executable`` automatically without prompting. This is
done from the checkbox in the confirmation dialog or from the ``Options`` menu in the
``Packages`` tool.

Manual Configuration
....................

If you need to find Poetry's virtualenv manually, this can be done by executing the
following command line in the directory where your ``pyproject.toml`` and ``poetry.lock`` 
are located::

  poetry run python -c "import sys, os; print(os.path.dirname(sys.executable))"

Then set ``Python Executable`` to ``Activated Env`` and enter the *full path* to the
virtualenv's activation script. On Windows this is in ``Scripts\activate.bat`` below the
directory printed by the above command. On macOS and Linux, this is ``activate`` instead.

Poetry Auto-Install
-------------------

If Poetry is the active package manager for a project, then Wing will ensure that
``poetry`` is installed into the base Python installation associated with the virtualenv
that Poetry creates.

There are several reasons that the ``poetry`` package may be missing from the active
Python base install:

(1) The user has elected to use Poetry in ``Project Properties`` or the ``Packages``
    tool's ``Options`` menu but ``poetry`` was never installed.
    
(2) The user has opened a project that caused Wing to auto-detect use of Poetry because 
    its home directory contains ``poetry.lock`` but Poetry was never installed.
    
(3) The Python version specified in ``pyproject.toml`` or ``poetry.lock`` does not match
    the version of Python that runs ``poetry`` initially. This may select a base Python
    installation that does not already have ``poetry``. 
    
Poetry does contain some functionality to re-launch with the correct Python version,
but Wing still auto-installs Poetry into the selected environment, in order to avoid
depending on another Python installation that may change over time.
    
In all cases, once Poetry has been initialized, the base install for the Poetry virtualenv
is used to invoke the ``poetry`` commands that implement package operations initiated from
the ``Packages`` tool.

Linux Note
..........

On Linux, Wing may fail to install Poetry because of conflicts with the resident package
manager (either RPM-based or Debian).  In this case you will need to install Poetry using
Linux package management, for example with 'apt install python3-poetry' or 'yum install
python3-poetry'.  The package name may vary by system.

Removing the Poetry Virtualenv
------------------------------

If ``poetry env remove` is executed to remove the virtualenv, Wing will not be able to debug or
execute code until Poetry's virtualenv is recreated, either with ``poetry install`` or
from Wing's ``Packages`` tool.

.. note::

  **Important**: If you are working on a remote host, container, or cluster and run
  ``poetry env remove`, Wing will lose contact with the remote system because it uses the
  configured ``Python Executable`` to run its remote agent. In this case, you will need to
  manually recreate Poetry's virtualenv by running ``poetry install`` on the remote system,
  in the directory that contains your ``poetry.lock``.
