<type>how-to</type>
<domain>howtos</domain>
<id>poetry</id>
<title>Using Wing with pipenv</title>
<date>$Date: 2012-11-15 15:25:42 -0500 (Thu, 15 Nov 2012) $</date>
<version>$Revision: 27651 $</version>
<product>pro+</product>

.. image:: /images/screenshots/wing7-screenshot-linen.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing Pro <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code running in a Python environment managed by `Poetry <https://python-poetry.org/>`__.

If you do not already have Wing Pro installed, `download it now <https://wingware.com/downloads/wingpro>`__.

This document describes how to configure Wing for Poetry. To get started using Wing as
your Python IDE, please refer to the tutorial in Wing's ``Help`` menu or read the
`Quickstart Guide <ref:howtos/quickstart>`__.

Creating a New Poetry Environment
---------------------------------

Wing Pro can create a new Poetry environment at the same time that you create a new project.
To do this, select ``New Project`` from the ``Project`` menu, choose the source directory
to use with your new project, and then press ``Next``.  

On the second page you will be able to select ``Create New Environment`` and choose
``Poetry`` from the menu of available environment types.

Wing uses your selected source directory as the Poetry directory.  You can optionally enter
the following values:

  ``Packages to Install`` lets you specify packages to install into the new virtualenv.
  This is either a space-separated list of pip package specifications, or package
  management file in one of several formats (requirements.txt, Pipfile, or
  environment.yaml). Package specifications may be anything accepted by pip, such as a
  package name, ``package==version``, and ``package>=version``.
  
  ``Python Executable`` selects the base Python installation to use.  You will need
  to install pip into this Python installation if not already present.  Wing takes
  care of installing Poetry as needed.

After submitting the ``New Project`` dialog, Wing will create the Poetry environment, set the
`Python Executable <script:view_project_properties#highlighted_attrib="proj.pyexec">`__ in
``Project Properties`` to the command that activates the environment, and add the
source directory to the project.

Now source analysis, executing, debugging, and testing in Wing will use the new
Poetry environment, as long as the project you just created is open.

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

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

Using an Existing Poetry Environment
------------------------------------

To use an existing Poetry environment with Wing, simply select the directory that contains
your ``poetry.lock`` as your source directory, under the ``Use Existing Directory`` option
in the ``New Project`` dialog. Wing will automatically detect that this directory contains
a Poetry environment and use it with your new project.

Working on a Remote Host
------------------------

Wing Pro can also create a new Poetry environment on a remote host.  This is done the same
way as described above, except you first need to choose or create a remote host 
configuration from the ``Host`` menu on the first page of the ``New Project`` dialog.

If you are using Poetry on the remote host, Wing will update the remote host
configuration to use the virtualenv created by Poetry (rather than the base Python
installation).

Package Management
------------------

Once you've configured your project to use Poetry, you can use the ``Packages`` tool in
the ``Tools`` menu to list, add, remove, or update packages. See `Package Manager
<ref:packages/intro>`__ for details.

Related Documents
-----------------

For more information see:

* `Package Management with Poetry <ref:packages/poetry>`__ contains some additional
  details about using Poetry with Wing.
  
* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing's features.

* `Wing Reference Manual <ref:manual>`__ documents Wing in detail.

