New config option to allow no hash in venv name

[zEdS15B3GCwq]

Pull Request Check List

Resolves: feature request #4862

• [x] Added tests for changed code.
• [x] Updated documentation for changed code.

Summary

Adds config option virtualenvs.path-independent_naming that omits the project path-dependent hash from newly created venv names.

The rationale behind this is that the hash was inconvenient in some use cases, e.g. project folders could not be moved without "losing" the existing venv; and sharing project folders (cloud storage or network share) was inconvenient as some local IDE (VSCode) settings would conflict between computers depending on the project path. This config option eliminates these issues.

Usage example:

mkdir projectname
cd projectname
poetry config --local virtualenvs.path-independent_naming true
poetry init # use default name etc.
poetry show # implicitly creates venv "projectname-pyX.Y", without path hash

Now the project folder can be moved, and poetry will keep using the same venv.

This setting is intended to be for personal use, i.e. NOT shared on git, same as other poetry settings.

Potential problems

Can confuse poetry if there are multiple projects with the same package name. However, this setting is not enabled by default, and I am assuming that users who enable it know what they're doing. And there's a warning in the documentation.

Otherwise, same potential issues as with in-project, i.e. changing the config when venvs already exist for the project causes new venvs to be created and the previous one is "lost" to poetry, unless the setting is reverted. This is not new.

Implementation

The referred issue (#4862) broadly talks about several possible solutions to the problems I mentioned here, and while I do believe that poetry's handling of venvs needs some rethinking from the ground up, here I aimed to minimize changes. The default behaviour is unaffected, so users won't notice the difference unless they need this option.

The code for path-independent_naming is a copy of in-project, at least as much as possible.

1. The biggest change is that generate_venv_name used to be a class method of EnvManager, but in order for it to be able to access the configuration, it was necessary to change it to a normal method. While this change is substantial in theory, I believe keeping it a class method and adding parameters would've been more disruptive.

2. Naturally, generate_venv_name accesses the configuration and if this setting is true, it skips adding the hash to the venv name.

3. Configuration documentation updated (config --list part and added new entry for option)

4. New option added as a copy of in-project in both configuration code and tests.

5. Tests changed from using class method to using EnvManager instance methods. Other code wasn't affected, I believe.

Naming

I tried to give it a name that describes what it can be used for, so that users who don't know how the venv names are generated can still understand the purpose. However, I feel that path-independent_naming is somewhat complicated and perhaps not descriptive enough. Suggestions are welcome.

[zEdS15B3GCwq]

Is the "Tests / FreeBSD / PYTHON:python3.6 Failing after 4s" error something that I'm supposed to fix? It seems to fail before even running the tests.

Update: nevermind, test has been removed apparently

[zEdS15B3GCwq]

Tested on master (1.2.0a2) with this patch; Python 3.9.9; Windows 11 x64

Setup:

Project folder:

 Directory of C:\Stuff\Code\test

2022. 01. 14.  14:46    <DIR>          .
2022. 01. 14.  14:46    <DIR>          ..
2022. 01. 14.  14:46               287 pyproject.toml
               1 File(s)            287 bytes

pyproject.toml (poetry init with default options):

[tool.poetry]
name = "test"
version = "0.1.0"
description = ""
authors = ["Your Name <[email protected]>"]

[tool.poetry.dependencies]
python = "^3.9"

[tool.poetry.dev-dependencies]

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

poetry:

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE --version
Poetry (version 1.2.0a2)

Venv creation with default config (hash included)

As expected, poetry creates new venv with hash included:

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE config --list
cache-dir = "C:\\Users\\R\\AppData\\Local\\pypoetry\\Cache"
experimental.new-installer = true
installer.max-workers = null
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "C:\\Users\\R\\Virtualenvs"
virtualenvs.path-independent_naming = null

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           NA
Executable:     NA

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\Virtualenvs\poetry_dev
Executable: C:\Users\R\Virtualenvs\poetry_dev\Scripts\python.exe

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE show
Creating virtualenv test-LT3l06US-py3.9 in C:\Users\R\Virtualenvs

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           C:\Users\R\Virtualenvs\test-LT3l06US-py3.9
Executable:     C:\Users\R\Virtualenvs\test-LT3l06US-py3.9\Scripts\python.exe
Valid:          True

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\.pyenv\pyenv-win\versions\3.9.9
Executable: python

Venv creation with option virtualenvs.path-independent_naming enabled

New venv has no hash in name:

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE config virtualenvs.path-independent_naming true

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE config --list
cache-dir = "C:\\Users\\R\\AppData\\Local\\pypoetry\\Cache"
experimental.new-installer = true
installer.max-workers = null
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "C:\\Users\\R\\Virtualenvs"
virtualenvs.path-independent_naming = true

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           NA
Executable:     NA

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\Virtualenvs\poetry_dev
Executable: C:\Users\R\Virtualenvs\poetry_dev\Scripts\python.exe

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE show
Creating virtualenv test-py3.9 in C:\Users\R\Virtualenvs

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           C:\Users\R\Virtualenvs\test-py3.9
Executable:     C:\Users\R\Virtualenvs\test-py3.9\Scripts\python.exe
Valid:          True

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\.pyenv\pyenv-win\versions\3.9.9
Executable: python

Changing option

Switching between hash-enabled and disabled state (much like toggling virtualenvs.in-project) works as expected:

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE config virtualenvs.path-independent_naming true

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           C:\Users\R\Virtualenvs\test-py3.9
Executable:     C:\Users\R\Virtualenvs\test-py3.9\Scripts\python.exe
Valid:          True

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\.pyenv\pyenv-win\versions\3.9.9
Executable: python

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE config virtualenvs.path-independent_naming false

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           C:\Users\R\Virtualenvs\test-LT3l06US-py3.9
Executable:     C:\Users\R\Virtualenvs\test-LT3l06US-py3.9\Scripts\python.exe
Valid:          True

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\.pyenv\pyenv-win\versions\3.9.9
Executable: python

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE config --unset virtualenvs.path-independent_naming

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           C:\Users\R\Virtualenvs\test-LT3l06US-py3.9
Executable:     C:\Users\R\Virtualenvs\test-LT3l06US-py3.9\Scripts\python.exe
Valid:          True

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\.pyenv\pyenv-win\versions\3.9.9
Executable: python

Renaming / moving project folder with option enabled

The same environment is being used even after a path change:

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE config virtualenvs.path-independent_naming true

C:\Stuff\Code\test>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           C:\Users\R\Virtualenvs\test-py3.9
Executable:     C:\Users\R\Virtualenvs\test-py3.9\Scripts\python.exe
Valid:          True

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\.pyenv\pyenv-win\versions\3.9.9
Executable: python

C:\Stuff\Code\test>cd ..

C:\Stuff\Code>rename test test2

C:\Stuff\Code>cd test2

C:\Stuff\Code\test2>C:\Users\R\Virtualenvs\poetry_dev\Scripts\poetry.EXE env info

Virtualenv
Python:         3.9.9
Implementation: CPython
Path:           C:\Users\R\Virtualenvs\test-py3.9
Executable:     C:\Users\R\Virtualenvs\test-py3.9\Scripts\python.exe
Valid:          True

System
Platform:   win32
OS:         nt
Python:     3.9.9
Path:       C:\Users\R\.pyenv\pyenv-win\versions\3.9.9
Executable: python

[zEdS15B3GCwq]

I'm aware that this PR is behind master and has conflicts due to other changes to config options. I'll handle that when/if it gets any attention.

Update: done

[neersighted]

Sorry to get to this after so much time -- as you can see, this repo is busy and larger changes can be hard to review. We're clearing the 1.2 release hangover so hopefully the backlog will get attacked more aggressively in the coming weeks.

Anyway, I am not sure there is a compelling reason to merge/introduce this. Poetry's virtual environment management is intentionally very minimal and simple. This is because Poetry has always respected an existing virtual environment and the bail-out for users wanting more than Poetry offers is to just use whatever pre/non-Poetry workflow and tooling they prefer.

Does this really offer anything over activating an environment and managing it however you like? Poetry's two settings of "treat the environment as a hidden implementation detail and abstract it for me" and "put it in the project" seem to be more than sufficient to me, and indeed, most use cases I have discussed or encountered.

[zEdS15B3GCwq]

Hi, thanks for taking time to review this.

Does this really offer anything over activating an environment and managing it however you like? Poetry's two settings of "treat the environment as a hidden implementation detail and abstract it for me" and "put it in the project" seem to be more than sufficient to me, and indeed, most use cases I have discussed or encountered.

I'd love to let Poetry manage the virtualenvs for me, but the current "take it or leave it" approach doesn't let me do that. Yes, I can manage my own environments, or I can just change Poetry to suit my own ways - and I do, but I'd rather I didn't need to. In my opinion, being configurable doesn't mean that Poetry can't be a tool that just takes care of things for you - it can enable Poetry to work well for more users.

To be honest, I think this option shouldn't be needed, because Poetry virtualenvs shouldn't depend on the project path in the first place - but then I'd be talking about design decisions, which is a more complex topic.

Ultimately, I have no idea how many other users would benefit from this setting. If you think not many, then there's no point in including it, indeed.

[Secrus]

@zEdS15B3GCwq thank you for your effort. Since there wasn't much progress on that feature (and it is not a direction we want to go with) I am going to close this.

[github-actions[bot]]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.