From 456218dca227bea29822121f2a64f032b7890667 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Mon, 16 Jan 2023 23:36:32 +0000 Subject: [PATCH 01/12] PEP 704: Require virtual environments by default for installers Enforce the use of virtual environments and establish a conventional name for the virtual environment directory. --- pep-0704.rst | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 pep-0704.rst diff --git a/pep-0704.rst b/pep-0704.rst new file mode 100644 index 00000000000..3642ce3a53e --- /dev/null +++ b/pep-0704.rst @@ -0,0 +1,137 @@ +PEP: 704 +Title: Require virtual environments by default for installers +Author: Pradyun Gedam +Sponsor: Brett Cannon +PEP-Delegate: Paul Moore +Discussions-To: https://discuss.python.org/t/22846 +Status: Draft +Type: Standards Track +Topic: Packaging +Content-Type: text/x-rst +Created: 16-Jan-2023 +Python-Version: 3.13 +Post-History: 16-Jan-2023 + + +Abstract +======== + +This PEP proposes that package installers like ``pip`` MUST require a virtual environment by default, on Python 3.13+. + +Motivation +========== + +Python virtual environments are an essential part of the development workflow for Python. However, it requires extra effort since it is an opt-in feature, and requires users to either: + +- take explicit steps to activate/deactivate a virtual environment +- use ``//`` to run files + +This creates a barrier to entry for many new users, since virtual environments serve as a pre-requisite for typical Python development workflows and how virtual environments work is a lot of information for anyone new. It can take a lot of extra time and effort to explain them. + +Further, activation of virtual environment uses a slightly different syntax/mechanism to activate on different platforms. + +It also creates a scope for mistakes, since users must remember to activate the virtual environment before running an installer like ``pip``. On certain Linux distributions, this can result in the installer modifying files that are owned by the operating system (this is partially mitigated by :pep:`668` for distributions that opt-in to marking their environments accordingly). + +This PEP proposes that the default behaviour of installers like ``pip`` should be to require a virtual environment to be active. This would make it easier for new users to get started with Python, and would reduce the scope for mistakes. + + +Specification +============= + +When a user runs an installer without an active virtual environment, the installer MUST print an error message and exit with a non-zero exit code. The error message MUST inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named ``.venv``, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment. + +The installer MUST also provide an command line option to disable this behaviour, allowing a user to opt-in to running the tool outside of a virtual environment. The installer MAY include this in the error message that it prints, and MUST include it in the documentation page it links to. + +If the installer includes a link to a documentation page in the error message described above, the documentation page SHOULD be written with a focus on new users. It should explain what virtual environments are, why they are required, and how to create and activate a virtual environment. It SHOULD include instructions for the most common shells and platforms. + +Installers MAY choose to implement this default behaviour on any Python versions, but MUST implement it on Python 3.13 or newer. + + +Backwards Compatibility +======================= + +This PEP is backwards incompatible with workflows where users who are using installers outside of virtual environments. Such users will be prompted with an error message and will need to either: + +- explicitly opt-in to running the installer outside of a virtual environment, or +- create and use a virtual environment + +Users who are already using virtual environments will not be affected by this change. + +Workflow tools (which manage virtual environments for the user, under the hood) should be unaffected, since they should already be using the virtual environment for running the installer. + + +Security Implications +===================== + +This PEP does not introduce any new security implications. + + +How to Teach This +================= + +This PEP does require that new users create and use a virtual environment to get started with using Python packages. This is however a best practice, as demonstrated by the section on "basics of how to install Python packages" in the Python Packaging User Guide, which explains how/what virtual environments are before discussing using ``pip``.[1]_ + + +Reference Implementation +======================== + +There is no reference implementation for this PEP, however the proposed behaviour is already implemented in ``pip`` and can be achieved by setting ``PIP_REQUIRE_VENV`` environment variable to ``1`` (not setting it would result in the proposed opt-in behaviour). + +Rejected Ideas +============== + +Do not specify a name for the virtual environment directory +----------------------------------------------------------- + +Using a consistent name for the virtual environment directory is important for a few reasons: + +1. It makes it easier for users to find the virtual environment directory, and to activate it. +2. It removes a decision point for new users, since they do not need to decide on a name for the virtual environment directory. +3. It creates a clear convention within the ecosystem, which makes it easier for users to find documentation. +4. It ensures consistency across different tools, so that differences in the error message of different tools do not confuse users. + +Use a different name for the virtual environment directory +---------------------------------------------------------- + +Functionally, the directory name does not matter much as long as there is a single consistent suggestion. + +The name ``.venv`` was picked since it: + +1. does not conflict with any valid Python import name +2. does not conflict ``venv`` module in the standard library +3. has pre-existing usage in the Python community +4. has support for auto-detection in common text editors +5. can be typed without modifier keys on common keyboard layouts + +Do not couple tooling behaviour with a Python version +----------------------------------------------------- + +This PEP creates a coupling between the behaviour of installers and the Python version, enforcing a behaviour change in installers based on a Python version. + +This is already a rollout mechanism being used for behaviour changes in the installation tooling. For example, ``pip`` on Python 3.11 will use ``importlib.metadata`` instead of ``pkg_resources`` for parsing/fetching package metadata, and ``sysconfig`` instead of ``distutils.sysconfig`` for getting the paths to unpack wheels into. + +The difference with those cases is that they're supposed to be largely transparent to end users. This PEP is proposing a behaviour change that is not transparent to end users, and requires them to take action. + +The primary benefit of this is that it allows for redistributors to adapt their tooling in time for the new Python version and provides a clear and consistent point for change across the ecosystem. It also puts a clear deadline on when the default behaviour will consistently require a virtual environment by default (once Python 3.12 goes end-of-life). + +The primary issue with this approach is that it enforces a behaviour change on users when they upgrade to a new Python version, which can hamper the adoption of a new Python version. However, this is a migration/upgrade for existing users and it is a common expectation that _some_ changes to be needed for migration/upgrades. + +The author of this PEP believes that enforcing the benefits of applying this consistently throughout the ecosystem with a deadline, outweigh the drawbacks of enforcing a best-practice on users when they upgrade. + + +Open Issues +=========== + +None. + + +Footnotes +========= + +.. [1] https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments + +Copyright +========= + +This document is placed in the public domain or under the +CC0-1.0-Universal license, whichever is more permissive. From 07f96658dbcd4bb1cb667256ca81e7effa35bbdd Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Tue, 17 Jan 2023 00:25:35 +0000 Subject: [PATCH 02/12] PEP 704: Relax the requirement for opting-out of required venv --- pep-0704.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep-0704.rst b/pep-0704.rst index 3642ce3a53e..fd65c0c5a10 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -40,7 +40,7 @@ Specification When a user runs an installer without an active virtual environment, the installer MUST print an error message and exit with a non-zero exit code. The error message MUST inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named ``.venv``, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment. -The installer MUST also provide an command line option to disable this behaviour, allowing a user to opt-in to running the tool outside of a virtual environment. The installer MAY include this in the error message that it prints, and MUST include it in the documentation page it links to. +The installer SHOULD also provide a mechanism to disable this behaviour, allowing a user to opt-in to running the tool outside of a virtual environment. The installer MAY include this in the error message that it prints, and MUST include it in the documentation page it links to. If the installer includes a link to a documentation page in the error message described above, the documentation page SHOULD be written with a focus on new users. It should explain what virtual environments are, why they are required, and how to create and activate a virtual environment. It SHOULD include instructions for the most common shells and platforms. From 067948d00ab8fd22fdb82b27333e0c7cb1dedd04 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Tue, 17 Jan 2023 01:02:24 +0000 Subject: [PATCH 03/12] PEP 704: Drop a redundant word Co-authored-by: Jelle Zijlstra --- pep-0704.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep-0704.rst b/pep-0704.rst index fd65c0c5a10..9c2a288aeca 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -50,7 +50,7 @@ Installers MAY choose to implement this default behaviour on any Python versions Backwards Compatibility ======================= -This PEP is backwards incompatible with workflows where users who are using installers outside of virtual environments. Such users will be prompted with an error message and will need to either: +This PEP is backwards incompatible with workflows where users are using installers outside of virtual environments. Such users will be prompted with an error message and will need to either: - explicitly opt-in to running the installer outside of a virtual environment, or - create and use a virtual environment From 1d43d16fafdc4e06868ab38503354896dba7cf64 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Wed, 18 Jan 2023 09:08:02 +0000 Subject: [PATCH 04/12] PEP 704: Retitle to avoid scope for confusion --- pep-0704.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep-0704.rst b/pep-0704.rst index 9c2a288aeca..2b6eb43d257 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -1,5 +1,5 @@ PEP: 704 -Title: Require virtual environments by default for installers +Title: Require virtual environments by default for package installers Author: Pradyun Gedam Sponsor: Brett Cannon PEP-Delegate: Paul Moore From b053be39c25d9eb46e82a058dd4a99e8f5929a20 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Wed, 18 Jan 2023 09:08:37 +0000 Subject: [PATCH 05/12] PEP 704: Amend headers as requested by PEP editors --- pep-0704.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pep-0704.rst b/pep-0704.rst index 2b6eb43d257..9018de53fa7 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -9,8 +9,7 @@ Type: Standards Track Topic: Packaging Content-Type: text/x-rst Created: 16-Jan-2023 -Python-Version: 3.13 -Post-History: 16-Jan-2023 +Post-History: `16-Jan-2023 `__ Abstract From 15f1455050eb71eda6f411030c95c5ebd0e910aa Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Wed, 18 Jan 2023 09:10:07 +0000 Subject: [PATCH 06/12] PEP 704: Clarify rationale and relax the specification This aligns the PEP more closely with the model we've used for the PEPs already. --- pep-0704.rst | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/pep-0704.rst b/pep-0704.rst index 9018de53fa7..bfd00050e01 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -15,35 +15,42 @@ Post-History: `16-Jan-2023 `__ Abstract ======== -This PEP proposes that package installers like ``pip`` MUST require a virtual environment by default, on Python 3.13+. +This PEP recommends that package installers like ``pip`` require a virtual environment by default, on Python 3.13+. + Motivation ========== -Python virtual environments are an essential part of the development workflow for Python. However, it requires extra effort since it is an opt-in feature, and requires users to either: +Python virtual environments are an essential part of the development workflow for Python. However, they require extra effort since they are an opt-in feature, and requires users to either: - take explicit steps to activate/deactivate a virtual environment -- use ``//`` to run files +- use :samp:`{}/{}/{}` to run files + +For new users, things will seemingly work correctly when virtual environments are not used until they don't. Further, activating a virtual environment uses slightly different syntax and mechanisms on different platforms. This complicates the introduction to virtual environments since now information and context about how/why they are useful needs to explained to justify adding additional steps to the workflow. -This creates a barrier to entry for many new users, since virtual environments serve as a pre-requisite for typical Python development workflows and how virtual environments work is a lot of information for anyone new. It can take a lot of extra time and effort to explain them. +It also creates a scope for mistakes, since users need to remember to activate the virtual environment before running an installer like ``pip`` or configure those installers to error out. On certain Linux distributions, forgetting to do so can result in the installer modifying files that are owned by the operating system (which is partially mitigated by :pep:`668` for distributions that opt-in to marking their environments accordingly). -Further, activation of virtual environment uses a slightly different syntax/mechanism to activate on different platforms. -It also creates a scope for mistakes, since users must remember to activate the virtual environment before running an installer like ``pip``. On certain Linux distributions, this can result in the installer modifying files that are owned by the operating system (this is partially mitigated by :pep:`668` for distributions that opt-in to marking their environments accordingly). +Rationale +========= + +Changing the default behaviour of installers like ``pip`` to require a virtual environment to be active would: -This PEP proposes that the default behaviour of installers like ``pip`` should be to require a virtual environment to be active. This would make it easier for new users to get started with Python, and would reduce the scope for mistakes. +- make it easier for new users to get started with Python (since there's a consistent experience and virtual environments are understood as a thing you're required to use) +- reduce the scope for accidental installation issues for all users by default (by explicitly flagging when you're not using a virtual environment). +Setting up a convention of placing the virtual environment in-tree in a directory named ``.venv`` removes an decision point for common workflows and creates a clear convention within the ecosystem. Specification ============= -When a user runs an installer without an active virtual environment, the installer MUST print an error message and exit with a non-zero exit code. The error message MUST inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named ``.venv``, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment. +When a user runs an installer without an active virtual environment, the installer SHOULD print an error message and exit with a non-zero exit code. The error message SHOULD inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named ``.venv``, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment. -The installer SHOULD also provide a mechanism to disable this behaviour, allowing a user to opt-in to running the tool outside of a virtual environment. The installer MAY include this in the error message that it prints, and MUST include it in the documentation page it links to. +The installer SHOULD also provide a mechanism to disable this behaviour, allowing a user to opt-in to running the tool outside of a virtual environment. The installer MAY include this in the error message that it prints, and SHOULD include it in the documentation page it links to. If the installer includes a link to a documentation page in the error message described above, the documentation page SHOULD be written with a focus on new users. It should explain what virtual environments are, why they are required, and how to create and activate a virtual environment. It SHOULD include instructions for the most common shells and platforms. -Installers MAY choose to implement this default behaviour on any Python versions, but MUST implement it on Python 3.13 or newer. +Installers MAY choose to implement this default behaviour on any Python versions, but SHOULD implement it on Python 3.13 or newer. Backwards Compatibility From a04b0abfc5309964272ab3936e04aee84aadf294 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Wed, 18 Jan 2023 09:10:31 +0000 Subject: [PATCH 07/12] PEP 704: Add whitespace for style consistency --- pep-0704.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/pep-0704.rst b/pep-0704.rst index bfd00050e01..fabe834d2f3 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -83,6 +83,7 @@ Reference Implementation There is no reference implementation for this PEP, however the proposed behaviour is already implemented in ``pip`` and can be achieved by setting ``PIP_REQUIRE_VENV`` environment variable to ``1`` (not setting it would result in the proposed opt-in behaviour). + Rejected Ideas ============== From 22e4a0707a8df8a1d58eb1a6064ed4592ca93cfa Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Wed, 18 Jan 2023 09:47:37 +0000 Subject: [PATCH 08/12] Clearly separate specification and implementation notes This should reduce scope for confusion on this front. --- pep-0704.rst | 46 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/pep-0704.rst b/pep-0704.rst index fabe834d2f3..86c8c853c53 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -44,11 +44,22 @@ Setting up a convention of placing the virtual environment in-tree in a director Specification ============= -When a user runs an installer without an active virtual environment, the installer SHOULD print an error message and exit with a non-zero exit code. The error message SHOULD inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named ``.venv``, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment. +Requiring a virtual environment by default +------------------------------------------ -The installer SHOULD also provide a mechanism to disable this behaviour, allowing a user to opt-in to running the tool outside of a virtual environment. The installer MAY include this in the error message that it prints, and SHOULD include it in the documentation page it links to. +When a user runs an installer without an active virtual environment, the installer SHOULD print an error message and exit with a non-zero exit code. -If the installer includes a link to a documentation page in the error message described above, the documentation page SHOULD be written with a focus on new users. It should explain what virtual environments are, why they are required, and how to create and activate a virtual environment. It SHOULD include instructions for the most common shells and platforms. +The error message SHOULD inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named ``.venv``, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment. + +See `Implementation notes`_ for more details. + +Opting out of virtual environments +---------------------------------- + +The installer SHOULD also provide a explicit opt-in before allowing an end user to use it outside of a virtual environment. If the installer does not provide this functionality, it SHOULD mention this in the error message and documentation page. + +Consistent timeline for the change +---------------------------------- Installers MAY choose to implement this default behaviour on any Python versions, but SHOULD implement it on Python 3.13 or newer. @@ -75,14 +86,34 @@ This PEP does not introduce any new security implications. How to Teach This ================= -This PEP does require that new users create and use a virtual environment to get started with using Python packages. This is however a best practice, as demonstrated by the section on "basics of how to install Python packages" in the Python Packaging User Guide, which explains how/what virtual environments are before discussing using ``pip``.[1]_ +This PEP does require that new users create and use a virtual environment to get started with using Python packages. This is however a best practice, as `demonstrated `__ by the section on "basics of how to install Python packages" in the Python Packaging User Guide, which explains how/what virtual environments are before discussing using ``pip``. Reference Implementation ======================== -There is no reference implementation for this PEP, however the proposed behaviour is already implemented in ``pip`` and can be achieved by setting ``PIP_REQUIRE_VENV`` environment variable to ``1`` (not setting it would result in the proposed opt-in behaviour). +There is no reference implementation for this PEP, however the proposed behaviour is largely implemented in ``pip`` and can be achieved by setting ``PIP_REQUIRE_VENV`` environment variable to ``1`` (not setting it would result in the proposed opt-in behaviour). + + +Implementation Notes +==================== + +Detecting an active virtual environment +--------------------------------------- + +:pep:`As discussed in PEP 668 <668#backwards-compatibility>`, the logic for robustly detecting a virtual environment is something like:: + def is_virtual_environment(): + return sys.base_prefix != sys.prefix or hasattr(sys, "real_prefix") + +Documentation on using a virtual environment +-------------------------------------------- + +Package installers are expected to provide a link to a documentation page in the error message. + +Ideally, such a documentation page would explain what virtual environments are, why they are required, and how to create and activate a virtual environment using ``venv``. It should include instructions for the most common shells and platforms. + +Such a documentation page should be made available in the `Python Packaging User Guide `__ to reduce duplicated effort across installers for covering this topic. Rejected Ideas ============== @@ -132,11 +163,6 @@ Open Issues None. -Footnotes -========= - -.. [1] https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments - Copyright ========= From 91f573f22a4e2014776938cb9c31e453b8e8c2e9 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Fri, 20 Jan 2023 20:39:33 +0000 Subject: [PATCH 09/12] PEP 704: Tweak phrasing Co-authored-by: C.A.M. Gerlach --- pep-0704.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep-0704.rst b/pep-0704.rst index 86c8c853c53..c5c53b69739 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -152,7 +152,7 @@ The difference with those cases is that they're supposed to be largely transpare The primary benefit of this is that it allows for redistributors to adapt their tooling in time for the new Python version and provides a clear and consistent point for change across the ecosystem. It also puts a clear deadline on when the default behaviour will consistently require a virtual environment by default (once Python 3.12 goes end-of-life). -The primary issue with this approach is that it enforces a behaviour change on users when they upgrade to a new Python version, which can hamper the adoption of a new Python version. However, this is a migration/upgrade for existing users and it is a common expectation that _some_ changes to be needed for migration/upgrades. +The primary issue with this approach is that it enforces a behaviour change on users when they upgrade to a new Python version, which can hamper the adoption of a new Python version. However, this is a migration/upgrade for existing users and it is a common expectation that *some* changes will be needed for migration/upgrades. The author of this PEP believes that enforcing the benefits of applying this consistently throughout the ecosystem with a deadline, outweigh the drawbacks of enforcing a best-practice on users when they upgrade. From a1951829dfb8f1ccca4ffefb7de1d7b299dc4383 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Fri, 20 Jan 2023 20:46:08 +0000 Subject: [PATCH 10/12] PEP 704: Add CODEOWNERS --- .github/CODEOWNERS | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index bdba43cade6..dd2d161842e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -584,6 +584,7 @@ pep-0700.rst @pfmoore pep-0701.rst @pablogsal @isidentical @lysnikolaou pep-0702.rst @jellezijlstra pep-0703.rst @ambv +pep-0703.rst @brettcannon @pradyunsg # ... # pep-0754.txt # ... From 011db9926a3f504dc81928a8ce4d8ae9c4df0856 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 22 Jan 2023 11:20:34 +0000 Subject: [PATCH 11/12] Update .github/CODEOWNERS Co-authored-by: Zak Johnson --- .github/CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index dd2d161842e..3d58230bff2 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -584,7 +584,7 @@ pep-0700.rst @pfmoore pep-0701.rst @pablogsal @isidentical @lysnikolaou pep-0702.rst @jellezijlstra pep-0703.rst @ambv -pep-0703.rst @brettcannon @pradyunsg +pep-0704.rst @brettcannon @pradyunsg # ... # pep-0754.txt # ... From fbf6837c77068ba044d4bbbe34ae1b64c7511745 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 22 Jan 2023 11:25:48 +0000 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- pep-0704.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/pep-0704.rst b/pep-0704.rst index c5c53b69739..14eeebc5891 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -15,7 +15,7 @@ Post-History: `16-Jan-2023 `__ Abstract ======== -This PEP recommends that package installers like ``pip`` require a virtual environment by default, on Python 3.13+. +This PEP recommends that package installers like ``pip`` require a virtual environment by default on Python 3.13+. Motivation @@ -26,7 +26,7 @@ Python virtual environments are an essential part of the development workflow fo - take explicit steps to activate/deactivate a virtual environment - use :samp:`{}/{}/{}` to run files -For new users, things will seemingly work correctly when virtual environments are not used until they don't. Further, activating a virtual environment uses slightly different syntax and mechanisms on different platforms. This complicates the introduction to virtual environments since now information and context about how/why they are useful needs to explained to justify adding additional steps to the workflow. +For new users, things will seemingly work correctly when virtual environments are not used -— until they don't. Further, activating a virtual environment uses slightly different syntax and mechanisms on different platforms. This complicates the introduction to virtual environments, since now information and context about how/why they are useful needs to explained to justify adding additional steps to the workflow. It also creates a scope for mistakes, since users need to remember to activate the virtual environment before running an installer like ``pip`` or configure those installers to error out. On certain Linux distributions, forgetting to do so can result in the installer modifying files that are owned by the operating system (which is partially mitigated by :pep:`668` for distributions that opt-in to marking their environments accordingly). @@ -39,7 +39,7 @@ Changing the default behaviour of installers like ``pip`` to require a virtual e - make it easier for new users to get started with Python (since there's a consistent experience and virtual environments are understood as a thing you're required to use) - reduce the scope for accidental installation issues for all users by default (by explicitly flagging when you're not using a virtual environment). -Setting up a convention of placing the virtual environment in-tree in a directory named ``.venv`` removes an decision point for common workflows and creates a clear convention within the ecosystem. +Setting up a convention of placing the virtual environment in-tree in a directory named ``.venv`` removes a decision point for common workflows and creates a clear convention within the ecosystem. Specification ============= @@ -51,12 +51,12 @@ When a user runs an installer without an active virtual environment, the install The error message SHOULD inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named ``.venv``, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment. -See `Implementation notes`_ for more details. +See :ref:`704-implementation` for more details. Opting out of virtual environments ---------------------------------- -The installer SHOULD also provide a explicit opt-in before allowing an end user to use it outside of a virtual environment. If the installer does not provide this functionality, it SHOULD mention this in the error message and documentation page. +The installer SHOULD also provide a explicit opt-in to disable this requirement, allowing an end user to use it outside of a virtual environment. If the installer does not provide this functionality, it SHOULD mention this in the error message and documentation page. Consistent timeline for the change ---------------------------------- @@ -74,7 +74,7 @@ This PEP is backwards incompatible with workflows where users are using installe Users who are already using virtual environments will not be affected by this change. -Workflow tools (which manage virtual environments for the user, under the hood) should be unaffected, since they should already be using the virtual environment for running the installer. +Workflow tools (which manage virtual environments for the user, under the hood) should be unaffected, since they should already be using a virtual environment for running the installer. Security Implications @@ -86,15 +86,17 @@ This PEP does not introduce any new security implications. How to Teach This ================= -This PEP does require that new users create and use a virtual environment to get started with using Python packages. This is however a best practice, as `demonstrated `__ by the section on "basics of how to install Python packages" in the Python Packaging User Guide, which explains how/what virtual environments are before discussing using ``pip``. +This PEP requires that new users create and use a virtual environment to get started with using Python packages. This is, however, a best practice, as `demonstrated `__ by the section on "basics of how to install Python packages" in the Python Packaging User Guide, which explains how/what virtual environments are before discussing using ``pip``. Reference Implementation ======================== -There is no reference implementation for this PEP, however the proposed behaviour is largely implemented in ``pip`` and can be achieved by setting ``PIP_REQUIRE_VENV`` environment variable to ``1`` (not setting it would result in the proposed opt-in behaviour). +There is no reference implementation for this PEP. However, the proposed behaviour is largely already implemented in ``pip`` and can be activated by setting the ``PIP_REQUIRE_VENV`` environment variable to ``1``. (Leaving it unset results in the proposed opt-in behaviour of not requiring a virtual environment for installation.) +.. _704-implementation: + Implementation Notes ==================== @@ -126,7 +128,7 @@ Using a consistent name for the virtual environment directory is important for a 1. It makes it easier for users to find the virtual environment directory, and to activate it. 2. It removes a decision point for new users, since they do not need to decide on a name for the virtual environment directory. 3. It creates a clear convention within the ecosystem, which makes it easier for users to find documentation. -4. It ensures consistency across different tools, so that differences in the error message of different tools do not confuse users. +4. It ensures consistency across different tools, so that differences in the error messages do not confuse users. Use a different name for the virtual environment directory ---------------------------------------------------------- @@ -144,7 +146,7 @@ The name ``.venv`` was picked since it: Do not couple tooling behaviour with a Python version ----------------------------------------------------- -This PEP creates a coupling between the behaviour of installers and the Python version, enforcing a behaviour change in installers based on a Python version. +This PEP creates a coupling between the behaviour of installers and the Python version. This is already a rollout mechanism being used for behaviour changes in the installation tooling. For example, ``pip`` on Python 3.11 will use ``importlib.metadata`` instead of ``pkg_resources`` for parsing/fetching package metadata, and ``sysconfig`` instead of ``distutils.sysconfig`` for getting the paths to unpack wheels into. @@ -154,7 +156,7 @@ The primary benefit of this is that it allows for redistributors to adapt their The primary issue with this approach is that it enforces a behaviour change on users when they upgrade to a new Python version, which can hamper the adoption of a new Python version. However, this is a migration/upgrade for existing users and it is a common expectation that *some* changes will be needed for migration/upgrades. -The author of this PEP believes that enforcing the benefits of applying this consistently throughout the ecosystem with a deadline, outweigh the drawbacks of enforcing a best-practice on users when they upgrade. +The author of this PEP believes that the benefits of applying this consistently throughout the ecosystem with a deadline outweigh the drawbacks of enforcing a best-practice on users when they upgrade. Open Issues pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy