PEP 832: virtual environment discovery

[cjames23 (Cary Hawkins)]

@blaisep

IDK if it justifies the work involved for WSP, but it strikes me as an advantage over redirect files.

Caveat: This is not ready to use or code complete
I started working on an implementation this weekend(with some AI assistance but always with me in the loop). But my hope is that we can have a centralized library that reduces such a burden cost for tools for implementation. For now I would just consider this a reference implementation of what I think this might look like for a WSP.

GitHub - cjames23/wispy: The whitespace between your workflow tool and...

[pf_moore (Paul Moore)]

Wow, that’s way more complex than I’d imagined. I didn’t look up what JSON-RPC involved, I’d assumed it was a “read a line of JSON from stdin, write a line of JSON to stdout, repeat” protocol. The wikipedia entry suggests that’s fine.

So I was expecting a minimal server to be pretty simple, certainly something that could be written in a single file with synchronous I/O.

If we need this much complexity, I’d want to change my vote to a Python protocol.

[cjames23 (Cary Hawkins)]

This is probably more complex than it needs to be because it’s 2.0 spec compliant and rather than adding additional dependencies I tried to keep it as pure as possible. But I do also hide a lot of the complexity for anyone that doesn’t want to deal with it by having the ability to drop a config that just tells the server the commands to call for each endpoint.

[steve.dower]

@pf_moore

Wow, that’s way more complex than I’d imagined. I didn’t look up what JSON-RPC involved

Yeah, sorry, I could’ve been more explicit about what it involves for the people who weren’t already familiar with it (though it felt a bit like bashing the other side, rather than advocating for my preference, which is why I didn’t go there). JSON-RPC is really only trivial if you rely on a helper library, which likely means a minimum 3 dependencies^[1]

@pf_moore

I’ll have a Python script (run using py /path/to/script.py) that implements a WSP server for this workflow, located somewhere on my system.

I want this workflow to apply for any tool I use

I don’t think we can mandate tool-specific configuration outside of our “scope”, which is the Python project. Telling VS Code “you must read configuration from this file and run the tool it mentions” is going to hit their security team immediately who will say “no way”.^[2] Similarly for GitHub Actions, which might otherwise want to be able to have a single action to implement this system apart from having to access a “user’s profile directory” that doesn’t exist.

This is not to say it’s not a good idea - it is - but it should be up to the tool to choose where that override is stored.

Paul, I feel like you’re assuming the most user-hostile front-end tool/IDE/etc. you can possibly imagine (they hate you so much they’re running arbitrary commands without your permission or invocation, and refusing to allow you to override), and then blaming their hostility on this interface. Please just blame the tool. If it’s a Microsoft-owned tool doing it to you, go ahead and point me or Brett at them and we’ll run complaints all the way up their management chain until the CEO is mad at them as well.

But please stop preemptively blaming the interface when the hostile tool [developer] is to blame.

---

1. Still better than the 30+ dependencies you’d need for Javascript ↩︎

2. That’s my unofficial opinion, as a member of said security team. Without a way to be confident the user is responsible for the setting - and they are ultimately responsible for the contents of the workspace - it’s going to end up being a painful experience. ↩︎

[pf_moore (Paul Moore)]

@steve.dower

I don’t think we can mandate tool-specific configuration outside of our “scope”, which is the Python project.

OK, but in the same vein, having project defined settings that the user can’t opt out of is just as much of a “no way” sort of situation. And it’s important to remember that individual users working on a project generally can’t change pyproject.toml to reflect their personal preferences.

At a minimum, I’d want the PEP to say that tools MUST provide a way for the user to disable workflow settings in pyproject.toml.

@steve.dower

But please stop preemptively blaming the interface when the hostile tool [developer] is to blame.

I’m not assuming hostility, simply laziness. In my experience, many tools (especially resource-constrained open source ones ) do the minimum required by the spec, and restrict anything beyond that to “stuff that doesn’t need too much thinking”.

Anyway, I’ve said my piece. I see little point in keeping on arguing. In my view, by giving projects a way to define a preferred workflow, but leaving any way for the user to define one as “tool UI”, puts us in a position of prioritising projects over users, and I think that’s the wrong way to handle a user facing configuration like workflow preferences. But it’s not my PEP, so all I can do is express that opinion. It’ll be up to the SC to make the decision.

(Hmm, saying that I’m assuming this will be a core PEP, not a packaging one. If it’s a packaging PEP, and I’m PEP-delegate, I’ll need to have a re-think, looking at what I think is best from an ecosystem POV, rather than just what I want for my wokflow…)

[brettcannon]

@pf_moore

unless you’re declaring those use cases as unsupported, it needs to. I don’t yet know what that solution will be, but why wouldn’t it also work for projects that do have a pyproject.toml?

It would, but that’s assuming we come up with some solution outside of pyproject.toml that people like.

The best I can think of is based off of Provide structured output for environment/interpreter discovery · brettcannon/python-launcher · Discussion #168 · GitHub and having workflow tools install an entry point with a certain name prefix like how Git plug-ins work (e.g. _py_wsp_<tool name>). The tricky bit with that is it would require asking all workflow tools whether they apply or not to a project on first run. Now, my guess is most people don’t have more than one workflow tool installed at once, so it wouldn’t be a huge concern or performance hit. You could also cache which tool said they should be the one to work with the project (or as a way to override if you manually set the cache). This doesn’t provide a way for a project to explicitly say, “please use this workflow tool” and allow overriding (e.g. committing some .python-wsp file wouldn’t be easy to override). But it’s one possible alternative approach that may avoid pyproject.toml. There’s also may be some combination of discovery via PATH and pyproject.toml that works out. Or environment variables to point at workflow tools locally.

@pf_moore

And too many of the key questions I have aren’t answered, except by a vague “your IDE might let you do this”. Sure it might, but equally it might not

Yep, just like any tool you use.

@pf_moore

But I use multiple tools (tox, nox, VS Code, vim, …) and I also want a tool-agnostic way to say “this is my preferred workflow”, and “please use my preference rather than the project recommendation”.

And yet all of those tools all have their own way of doing things, and I don’t know where they draw the line on what they are okay with us dictating to them for how they operate.

@pf_moore

Wow, that’s way more complex than I’d imagined. I didn’t look up what JSON-RPC involved, I’d assumed it was a “read a line of JSON from stdin, write a line of JSON to stdout, repeat” protocol.

You can if you don’t care about being as robust as the code Cary showed is. The spec is at JSON-RPC 2.0 Specification and as you can see it isn’t very long or complicated.

@pf_moore

you can’t say the PEP supports a use case by assuming that tools implementing the PEP will support that use case without the PEP requiring them to…

I wouldn’t say it supports it as much as wouldn’t prevent it while encouraging tools to support it.

@pf_moore

I’d want to change my vote to a Python protocol.

That’s fair, but I will say the workflow tool authors who voted seemed to prefer the JSON-RPC approach.

@steve.dower

JSON-RPC is really only trivial if you rely on a helper library, which likely means a minimum 3 dependencies

And why supporting inline script metadata would be important.

@pf_moore

At a minimum, I’d want the PEP to say that tools MUST provide a way for the user to disable workflow settings in pyproject.toml.

Do we mandate allowing people to opt out of a setting for any other standard?

@pf_moore

Hmm, saying that I’m assuming this will be a core PEP, not a packaging one. If it’s a packaging PEP, and I’m PEP-delegate, I’ll need to have a re-think, looking at what I think is best from an ecosystem POV, rather than just what I want for my wokflow…

That I don’t know. I expect to remove the changes to the venv module which required needing the SC to be the ones deciding on this PEP. If I move forward with using pyproject.toml then it might get messy as to whose “jurisdiction” the PEP falls under.

---

To try and tie all of this back to the problem I’m trying to solve: how do we make it so tools like VS Code know where any environments exist (if any)? There’s a matrix here (do note that “fancier” support subsumes simpler ones, e.g. WSP can also cover what .python-envs does):

Preference	First time loading the project	Already run workflow tool
Project has a preference	pyproject.toml	.python-envs
User has a preference	VS Code supports it?	.python-envs
No one cares	VS Code’s choice?	.venv

These are the scenarios I’m looking to (potentially) cover. Basically the bootstrapping of a fresh checkout is the “hard” problem to solve here.

[lucascolley]

@brettcannon

Preference	First time loading the project	Already run workflow tool
Project has a preference	pyproject.toml	.python-envs
User has a preference	VS Code supports it?	.python-envs
No one cares	VS Code’s choice?	.venv

This sounds useful to me. A potential problem scenario, however, is when a user ‘has a preference’ for a tool that can only install from PyPI, but a project ‘has a preference’ for a tool that can actually install all of its dependencies, e.g. for Pixi installing compilers from conda-forge. I suppose this could be the case if someone with a penchant for a PyPI-only tool were to look at contributing to SciPy right now.

What should VSCode do in such a scenario? Should it try to use the user’s preferred tool, on the assumption that non-PyPI dependencies are satisfied, potentially yielding an error? Or should it override that preference? I’m not sure if there is a good general answer. At this point it is probably fair to worry that such cases extend beyond the scope of a PEP, but I think they are important cases nonetheless.

To be honest, I don’t think it would be so bad for IDEs and the like to default to project recommendations, so long as they provide reasonable UIs for opting-in to overriding those recommendations in individual cases. In my experience of introducing a new developer workflow to SciPy, there is genuine friction for a small number of active and long-time developers, but almost everyone else who is new to the project or who does not tend to keep up with the latest developer workflow changes benefits. If we assume that projects are not adopting significantly objectionable tools as preferred on a wide scale, having overriding project-preferred tools be opt-in seems like a relatively low-friction requirement, primarily affecting long-time developers and hobbyists who have their reasons for differing from a given project’s recommendations. That seems plausibly worthwhile for the benefit of frictionless defaults for new or returning developers, IMO.

[tmk (Thomas Kehrenberg)]

@brettcannon

• UTF-8 encoded to contain paths which each represent an environment

Wouldn’t it be useful to have some kind of name associated with the environments, in order to give the user more information when choosing the environment to use? I kind of foresee being confronted with a list of 10 environments, not knowing which one to choose and then deciding to create the 11th one.

The file could also be JSON or some other widespread file format.

[steve.dower]

@lucascolley

What should VSCode do in such a scenario? Should it try to use the user’s preferred tool, on the assumption that non-PyPI dependencies are satisfied, potentially yielding an error?

Yes. If the user says “use this tool” then VS Code should say “okay, the project said to use tool X, but I’m using your override tool Y, so if it fails you’ll need to debug it yourself”, and if the user then complains to the project then the project will close it with “we said to use tool X, we don’t support tool Y” and the only person who’s unhappy is the one who ignored the instructions.

[lucascolley]

I agree, on the assumption that the ‘use this tool’ instruction is just a blanket command for ‘one tool fits any project with a Python environment’. Maybe what this example draws out though is that VSCode should allow for user-preferences to be conditional on whether the project has non-PyPI dependencies (or perhaps also allow the user to allow- / block-list certain project recommendations). I appreciate that one may want to wait for PEP 725 – Specifying external dependencies in pyproject.toml | peps.python.org before handling the former case.

[steve.dower]

@lucascolley

Maybe what this example draws out though is that VSCode should allow for user-preferences to be conditional on whether the project has non-PyPI dependencies

That’s never going to be implemented - they’ll implement a per-workspace override, as well as a per-user (and per-machine) override, because that’s the configuration hierarchy they already support.

We don’t have to tell them how to implement their product. We do need to give some amount of permission, because too many people assume that things we define like this are really strict^[1] (and too many others will file bugs because they assume they’re incredibly strict), but we don’t have to spell out how to design a user-friendly product.

---

1. The specification of the settings in the pyproject.toml are strict, because that’s interoperability - if you write the wrong thing, others don’t have to be able to read it - but the UX around choosing to activate it is not. ↩︎

[lucascolley]

@steve.dower

we don’t have to spell out how to design a user-friendly product

Of course, I’m just trying to check what the implications are for this PEP if we extend Paul’s concerns into the land of external dependencies and do not narrowly focus on VS Code’s existing configuration hierarchy.

It would be a shame, for example, if a user wanted their IDE to make a smart decision about how to bootstrap a fresh checkout based on whether external dependencies are required, but the IDE had no way to tell due to a lack of expression in pyproject.toml. Anyway, this thread can probably conclude since it doesn’t seem like anything is missing from this PEP for that case, rather we are left wanting PEP 725 – Specifying external dependencies in pyproject.toml | peps.python.org.

[brettcannon]

@lucascolley

This sounds useful to me.

As in you want all the solutions in the matrix? I.e. you would want WSP and .python-envs?

@lucascolley

when a user ‘has a preference’ for a tool that can only install from PyPI, but a project ‘has a preference’ for a tool that can actually install all of its dependencies, e.g. for Pixi installing compilers from conda-forge.

As Steve said, that’s their problem for choosing to ignore what the project said you should use to contribute.

@lucascolley

I don’t think it would be so bad for IDEs and the like to default to project recommendations, so long as they provide reasonable UIs for opting-in to overriding those recommendations in individual cases.

So this is the difference between fallback and override. I believe Paul wants the ability to override a project’s choice, while I personally want to be able to specify a fallback in case a project has no expressed preference.

@tmk

Wouldn’t it be useful to have some kind of name associated with the environments, in order to give the user more information when choosing the environment to use?

At least virtual environments already do: the prompt which is recorded in pyvenv.cfg. So I don’t think there’s a need to invent a second place to store such details.

@tmk

The file could also be JSON or some other widespread file format.

I would rather not as that seems like more ceremony than necessary for something that’s so simple. Plus it makes it harder to add something to a .python-envs file compared to echo "my-venv" >> .python-envs or Add-Content .python-envs "my-venv".

[lucascolley]

@brettcannon

@lucascolley

This sounds useful to me.

As in you want all the solutions in the matrix? I.e. you would want WSP and .python-envs?

Yes, I can see the complementary usefulness.

@brettcannon

@lucascolley

I don’t think it would be so bad for IDEs and the like to default to project recommendations, so long as they provide reasonable UIs for opting-in to overriding those recommendations in individual cases.

So this is the difference between fallback and override. I believe Paul wants the ability to override a project’s choice, while I personally want to be able to specify a fallback in case a project has no expressed preference.

Yes, in those terms, even though I tend to agree with the notion that ‘projects know best’, I think it is important to enable the possibility of overriding a project’s choice, on bootstrapping a fresh checkout as well as for subsequent use. While a certain tool may be the clear winner for the development of a project in general, it may not be beneficial for those performing only certain kinds of development.

In that quotation, I was expressing the view that user-/machine-level overrides seem less important, as long as one has project-level overrides.

I agree that fallback is also important.

[brettcannon]

I think things have calmed down enough that I think people understand the options being presented. That means it’s time to see what people think I should do with the PEP.

Below is a ranked choice poll I’m running for a week (until next Friday). The options run from “you’re wasting your time, Brett”, to “all the things!”, and various combinations in between. You will notice that if the PEP happens then I’m keeping .venv as a reasonable directory name suggestion for a virtual environment no matter what (but I will take out the changes to the stdlib as part of the PEP and make it a “MAY” suggestion). I’m also giving folks another chance on the Python API (like PEP 517) versus JSON-RPC for WSP as at least @pf_moore seemed taken aback by what that could mean, so I want to make sure people are making an informed decision here.

As a reminder:

• PEP 832: virtual environment discovery - #90 by brettcannon summarizes things
• PEP 832: virtual environment discovery - #108 by brettcannon has a table at the end about when various things come into play (and FYI pyproject.toml is WSP if that isn’t clear)
• API for discovering environments for a project is the discussion about JSON-RPC versus a Python API for WSP
• A CLI for WSP is expected and is assumed to support a simple fallback workflow that uses a .venv directory for scripting and AI model use

Do note that I am recording people’s votes as it does matter if all the workflow tool authors go a certain way. I also consider the poll results advisory and not binding.

With that all out of the way …

What should I do with PEP 832?

• Withdraw the PEP
• .venv and .python-envs
• .venv, .python-envs, and WSP over JSON-RPC
• .venv, .python-envs, and WSP as a Python API
• .venv and WSP over JSON-RPC
• .venv and WSP as a Python API

[EDIT: added “reminder” bullet list which reiterated things already said elsewhere that came up in private discussion with others.]