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

When `pipenv <https://pipenv.pypa.io/en/latest/>`__ is used for package management, Wing
runs ``pipenv`` command lines to implement the package operations.  

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

When using pipenv, the ``Python Executable`` in Wing's ``Propect Properties`` should be
set to the virtualenv created by pipenv. 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 pipenv's virtualenv manually, this can be done by executing the
following command line in the directory where your ``Pipfile`` is located::

  pipenv --venv

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`` within the
directory printed by the above command. On macOS and Linux, this is ``bin/activate``
instead.

Pipenv Auto-Install
-------------------

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

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

(1) The user has elected to use ``pipenv`` in ``Project Properties`` or the ``Packages``
    tool's ``Options`` menu but ``pipenv`` was never installed.
    
(2) The user has opened a project that caused Wing to auto-detect use of pipenv because 
    its home directory contains ``Pipfile`` but pipenv was never installed.
    
(3) The ``python_version`` specifier in ``Pipfile`` is set to a value that does not 
    match the version of Python that runs ``pipenv`` initially, or the ``--python``
    command line option was given when originally creating the pipenv virtualenv with
    ``pipenv install``. This may select a base Python installation that does not already
    have ``pipenv``. Wing installs it to avoid the confusing complexity of tracking
    multiple Python installations.
    
In all cases, once pipenv has been initialized, the base install for the pipenv virtualenv
is used to invoke the ``pipenv`` commands that implement package operations initiated from
the ``Packages`` tool.

Removing the pipenv Virtualenv
------------------------------

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

.. note::

  **Important**: If you are working on a remote host, container, or cluster and run
  ``pipenv --rm``, 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 pipenv's virtualenv by running ``pipenv install`` on the remote system,
  in the directory that contains your ``Pipfile``.

Selecting Python Version
------------------------

The Python version to use for pipenv's virtualenv does not have to be the same Python
version used to run pipenv.  This can be set in the ``Pipfile`` as follows::

  [requires]
  python_version = "3.8"
  
This section should be present already in the automatically generated ``Pipfile``
created by ``pipenv``, or can be added if missing.

You will need to run ``pipfile --rm`` and ``pipfile install`` outside of Wing to
actually change to the newly selected Python version.

