2015-02-12 14:13:56 -05:00
|
|
|
|
PEP: 486
|
|
|
|
|
Title: Make the Python Launcher aware of virtual environments
|
|
|
|
|
Version: $Revision$
|
|
|
|
|
Last-Modified: $Date$
|
|
|
|
|
Author: Paul Moore <p.f.moore@gmail.com>
|
2015-03-13 11:17:26 -04:00
|
|
|
|
Status: Final
|
2015-02-12 14:13:56 -05:00
|
|
|
|
Type: Standards Track
|
|
|
|
|
Content-Type: text/x-rst
|
|
|
|
|
Created: 12-Feb-2015
|
|
|
|
|
Python-Version: 3.5
|
2015-02-26 17:19:06 -05:00
|
|
|
|
Post-History: 12-Feb-2015
|
|
|
|
|
Resolution: https://mail.python.org/pipermail/python-dev/2015-February/138579.html
|
2015-02-12 14:13:56 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Abstract
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
The Windows installers for Python include a launcher that locates the
|
2022-01-21 06:03:51 -05:00
|
|
|
|
correct Python interpreter to run (see :pep:`397`). However, the
|
2015-02-12 14:13:56 -05:00
|
|
|
|
launcher is not aware of virtual environments (virtualenv [1]_ or PEP
|
|
|
|
|
405 based), and so cannot be used to run commands from the active
|
|
|
|
|
virtualenv.
|
|
|
|
|
|
|
|
|
|
This PEP proposes making the launcher "virtualenv aware". This means
|
|
|
|
|
that when run without specifying an explicit Python interpreter to
|
|
|
|
|
use, the launcher will use the currently active virtualenv, if any,
|
|
|
|
|
before falling back to the configured default Python.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rationale
|
|
|
|
|
=========
|
|
|
|
|
|
|
|
|
|
Windows users with multiple copies of Python installed need a means of
|
|
|
|
|
selecting which one to use. The Python launcher provides this
|
|
|
|
|
facility by means of a ``py`` command that can be used to run either a
|
|
|
|
|
configured "default" Python or a specific interpreter, by means of
|
|
|
|
|
command line arguments. So typical usage would be::
|
|
|
|
|
|
|
|
|
|
# Run the Python interactive interpreter
|
|
|
|
|
py
|
|
|
|
|
|
|
|
|
|
# Execute an installed module
|
|
|
|
|
py -m pip install pytest
|
|
|
|
|
py -m pytest
|
|
|
|
|
|
|
|
|
|
When using virtual environments, the ``py`` launcher is unaware that a
|
|
|
|
|
virtualenv is active, and will continue to use the system Python. So
|
|
|
|
|
different command invocations are needed to run the same commands in a
|
|
|
|
|
virtualenv::
|
|
|
|
|
|
|
|
|
|
# Run the Python interactive interpreter
|
|
|
|
|
python
|
|
|
|
|
|
|
|
|
|
# Execute an installed module (these could use python -m,
|
2015-02-26 17:19:06 -05:00
|
|
|
|
# which is longer to type but is a little more similar to the
|
2015-02-12 14:13:56 -05:00
|
|
|
|
# launcher approach)
|
|
|
|
|
pip install pytest
|
|
|
|
|
py.test
|
|
|
|
|
|
2016-05-03 05:03:16 -04:00
|
|
|
|
Having to use different commands is error-prone, and in many cases
|
2015-02-12 14:13:56 -05:00
|
|
|
|
the error is difficult to spot immediately. The PEP proposes making
|
|
|
|
|
the ``py`` command usable with virtual environments, so that the first
|
|
|
|
|
form of command can be used in all cases.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Implementation
|
|
|
|
|
==============
|
|
|
|
|
|
|
|
|
|
Both ``virtualenv`` and the core ``venv`` module set an environment
|
|
|
|
|
variable ``VIRTUAL_ENV`` when activating a virtualenv. This PEP
|
|
|
|
|
proposes that the launcher checks for the ``VIRTUAL_ENV`` environment
|
|
|
|
|
variable whenever it would run the "default" Python interpreter for
|
|
|
|
|
the system (i.e., when no specific version flags such as ``py -2.7``
|
|
|
|
|
are used) and if present, run the Python interpreter for the
|
|
|
|
|
virtualenv rather than the default system Python.
|
|
|
|
|
|
2022-01-21 06:03:51 -05:00
|
|
|
|
The "default" Python interpreter referred to above is (as per :pep:`397`)
|
2015-02-12 14:13:56 -05:00
|
|
|
|
either the latest version of Python installed on the system, or
|
|
|
|
|
a version configured via the ``py.ini`` configuration file. When the
|
|
|
|
|
user specifies an explicit Python version on the command line, this
|
|
|
|
|
will always be used (as at present).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Impact on Script Launching
|
|
|
|
|
==========================
|
|
|
|
|
|
2015-02-14 10:33:55 -05:00
|
|
|
|
|
2015-02-12 14:13:56 -05:00
|
|
|
|
As well as interactive use, the launcher is used as the Windows file
|
|
|
|
|
association for Python scripts. In that case, a "shebang" (``#!``)
|
|
|
|
|
line at the start of the script is used to identify the interpreter to
|
|
|
|
|
run. A fully-qualified path can be used, or a version-specific Python
|
|
|
|
|
(``python3`` or ``python2``, or even ``python3.5``), or the generic
|
|
|
|
|
``python``, which means to use the default interpreter.
|
|
|
|
|
|
2015-02-14 10:33:55 -05:00
|
|
|
|
The launcher also looks for the specific shebang line
|
|
|
|
|
``#!/usr/bin/env python``. On Unix, the ``env`` program searches for a
|
|
|
|
|
command on ``$PATH`` and runs the command so located. Similarly, with
|
|
|
|
|
this shebang line, the launcher will look for a copy of ``python.exe``
|
|
|
|
|
on the user's current ``%PATH%`` and will run that copy.
|
2015-02-12 14:13:56 -05:00
|
|
|
|
|
2015-02-14 10:33:55 -05:00
|
|
|
|
As activating a virtualenv means that it is added to ``PATH``, no
|
|
|
|
|
special handling is needed to run scripts with the active virtualenv -
|
|
|
|
|
they just need to use the ``#!/usr/bin/env python`` shebang line,
|
|
|
|
|
exactly as on Unix. (If there is no activated virtualenv, and no
|
|
|
|
|
``python.exe`` on ``PATH``, the launcher will look for a default
|
|
|
|
|
Python exactly as if the shebang line had said ``#!python``).
|
2015-02-12 14:13:56 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Exclusions
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
The PEP makes no attempt to promote the use of the launcher for
|
|
|
|
|
running Python on Windows. Most existing documentation assumes the
|
|
|
|
|
user of ``python`` as the command to run Python, and (for example)
|
|
|
|
|
``pip`` to run an installed Python command. This documentation is not
|
|
|
|
|
expected to change, and users who choose to manage their ``PATH``
|
|
|
|
|
environment variable can continue to use this form. The focus of this
|
|
|
|
|
PEP is purely on allowing users who prefer to use the launcher when
|
|
|
|
|
dealing with their system Python installations, to be able to continue
|
|
|
|
|
to do so when using virtual environments.
|
|
|
|
|
|
|
|
|
|
|
2015-02-14 10:33:55 -05:00
|
|
|
|
Reference Implementation
|
|
|
|
|
========================
|
|
|
|
|
|
|
|
|
|
A patch implementing the proposed behaviour is available at
|
|
|
|
|
http://bugs.python.org/issue23465
|
|
|
|
|
|
|
|
|
|
|
2015-02-12 14:13:56 -05:00
|
|
|
|
References
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
.. [1] https://virtualenv.pypa.io/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Copyright
|
|
|
|
|
=========
|
|
|
|
|
|
|
|
|
|
This document has been placed in the public domain.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
..
|
|
|
|
|
Local Variables:
|
|
|
|
|
mode: indented-text
|
|
|
|
|
indent-tabs-mode: nil
|
|
|
|
|
sentence-end-double-space: t
|
|
|
|
|
fill-column: 70
|
|
|
|
|
coding: utf-8
|
|
|
|
|
End:
|