Extension API: How to map it to hatch?

[flying-sheep]

Hi! I started implementing https://github.com/flying-sheep/vscode-hatch

Hatch’s env model is:

1. there are a few pre-defined ones and you can define more
2. you can create, destroy, and sync any defined env for a project, but none that aren’t pre-defined or defined in Hatch’s config

How should we map this to the extension API?

• create only makes sense for defined envs. So show a picker dialog for defined envs?
• remove ditto
• set & get doesn’t really make sense for Hatch. Would be best if these were optional to implement and this extension didn’t have to track the active env
• refresh … I don‘t know what it’s for. Is this supposed to re-fetch the list of defined envs or created envs?
• getEnvironments ditto. I think for Hatch it would make more sense if it returned the list of defined envs and we could respond to onTryingToSetEnvironment event or so to create it
• clearCache I also don’t know what this is for

I think in general it would be nice to have some examples when these are called. Like what UI action leads to clearCache being called?

cc @karthiknadig

[karthiknadig]

Thanks for working on the Hatch extension. I can provide some guidance here ( I may have to break it into individual comments).

Real-World Scenarios these APIs Support

The extension needs to handle a wide range of scenarios, including:

• Single Workspace, Single Environment (1:1): Straightforward and very common there’s one obvious Python to use. get returns it, set is a no-op.

• Single Workspace, Multiple Environments (1:N): This includes test/prod splits or monorepos with many envs (e.g., Azure SDK with 390+). Here, users need to switch between envs for different workflows. set is essential to reflect user intent in the IDE, if it is not already obvious from some other mechanism that get cannot disambiguate, or if get "picks" the wrong one.

• Multi-Root Workspaces (M:N): Each project root might use a different Python. The extension must support selecting environments per workspace folder. This again requires get and set to coordinate tools like notebooks, language servers, and linters.

Remarks: Rather than designing for just the simplest case, the API enables flexible handling of general M:N environments, with optimizations for common 1:1 workflows.

How the Extension Uses get and set

These APIs form the backbone of the Python experience with the extension. When the extension activates, it queries the registered environment manager using get. The result is used across tools like the language server, static analysis, formatters, linters, and debuggers.

For notebooks, set may be called with a notebook URI to associate that kernel with an env. You can use caching internally to remember and quickly return that choice via get later.

If your getEnvironments() only returns a single environment, set will naturally be a no-op, and that’s perfectly fine.

But in any non-trivial setup (multi-envs, multi-roots, notebooks), set lets the user steer the experience, and your implementation can respond however fits your philosophy, whether by updating config, creating envs, validating user input, or showing the user error of their ways. (Also, open to discussing an API that blocks set).

onDidChangeEnvironment Optional but powerful: triggering this lets downstream tools (e.g. language servers) re-fetch the active interpreter and reprocess code accordingly. If your tool ever changes environments implicitly or as part of a set, triggering this ensures a smooth and reactive experience.

Bottom line: while hatch may not have a first-class concept of an “active” environment, these APIs aren’t trying to impose that. They're meant to expose just enough control so IDE tooling can function predictably, especially in more complex workspace setups. You're free to implement them in a way that makes sense for your model, even if that means set is a no-op in some contexts

Copied my comment from here: InSyncWithFoo/uv-for-vscode#8 (comment) making it easier to find.

[karthiknadig]

getEnvironments and its scopes

This method allows an extension to return the list of environments it manages, tailored by scope. This makes it quite flexible depending on what the user or the extension needs:

• Workspace Uri: Return environments relevant to the project at the given location. For Hatch, this might be a single pre-defined environment, or a small set of environments defined in pyproject.toml. You may choose to create the environment at this point or better, pre-create it in the background when the extension loads.

• global scope: This is used when creating new environments, typically showing the base Python installations (e.g., system Pythons, known versions). For Hatch, this might return a list of Python versions available on the system that could be used to bootstrap a new env.

• all scope: Used to show all environments known to the extension. You can define what "all" means. venv only shows envs in opened workspaces, conda shows everything. Hatch can similarly return all known defined environments across all workspaces, or just those currently relevant.

The point is: you control the logic here. If Hatch is highly declarative (i.e., only knows about environments defined in config), this model fits well.

refresh handling

This is a user-initiated signal saying “I don’t see what I expect go re-scan.”. It gives you the opportunity to:

• Re-read pyproject.toml and see if new environments have been added.
• Check whether any previously defined envs have been created or deleted.
• Optionally call onDidChangeEnvironments if there are changes.

If you’re already handling config edits reactively (see next section), this may rarely be used.

Using onDidChangeEnvironments

You can detect changes by adding file system watchers (see createFileSystemWatcher API in VS Code). This event lets you proactively notify the Python extension that something changed:

• A user added or removed an environment in pyproject.toml
• An environment was synced or deleted
• An environment’s status changed (e.g., it became “created” after background sync)

This is your chance to keep the UI in sync. It’s optional, but if you want users to see changes reflected immediately, it’s worth implementing. And don’t forget: if an environment becomes the new “active” one, you can also trigger onDidChangeEnvironment for a specific URI to signal that downstream tools (like LS, debugger, etc.) should respond.

[karthiknadig]

When to use clearCache

This is an optional method that can be implemented by environment managers to support user-driven cache clearing. It’s invoked when users run the Python: Clear Cache command from the Command Palette.

The goal is to give users a way to reset any internal state your extension may be holding, especially if:

• The list of environments appears stale or incorrect
• A config change isn’t being reflected
• Reloading VS Code hasn’t resolved the issue

You should only implement this if your extension uses some form of caching to speed up resolution (e.g., storing environment metadata, resolved paths, config state, etc.). When implemented, this gives users a non-destructive recovery tool to fix odd environment behavior without needing to fully reload the IDE.

[flying-sheep]

Thank you! That clears some things up! A few more questions in bold below

You may choose to create the environment at this point or better, pre-create it in the background when the extension loads.

Hmm, that’s not how I tend to use Hatch. I sometimes hatch env prune to start with a clean slate and then don’t waste time re-creating all envs but just create the one I need.

Ideally, I’d have getEnvironments return a list of declared environments (that might or might not exist yet) and create them when trying to set as active or run things in them. Is that possible?

Also, I currently have an issue, probably because I don’t understand get and set: flying-sheep/vscode-hatch#1

global scope: […] For Hatch, this might return a list of Python versions available on the system that could be used to bootstrap a new env.

Do I really have to re-create all that logic? Can’t I just let the base extension handle these and return nothing?

[karthiknadig]

Ideally, I’d have getEnvironments return a list of declared environments (that might or might not exist yet) and create them when trying to set as active or run things in them. Is that possible?

You would need to create the one that you want the project to use when get is called. That said you don't have to create them for getEnvironments, you can return a list of potentially available environments. Typically, there should be something that downstream tools like Language Servers and Static analysis can use as soon as the extension loads.

Assume this config:

[tool.hatch.envs.default]
dependencies = [ "foo",  "bar",]

[tool.hatch.envs.test]
dependencies = ["pytest"]

When get is called you would need to have default environment created, if it doesn't already exist on disk, with the required packages installed. This will allow all the downstream tools to use that environment. Users may later while developing switch the environment to test to run tests. This is when set will get called. You can create it and trigger the onDidChangeEnvironment. get will be called when something needs it, often it will get called immediately after set.

Do I really have to re-create all that logic? Can’t I just let the base extension handle these and return nothing?

Not really, you could return [] (empty) array for global scope for now. See how your users respond to those cases and then decide.

Also, I currently have an issue, probably because I don’t understand get and set: flying-sheep/vscode-hatch#1

I can help with this, later in the week though.

[flying-sheep]

OK, more questions:

• something remembers what the active env is: is that the Python extension? How can I ask for that inside of activate?
• how can I get a list of active Python projects inside of activate in case there’s no env selected for a project (so that I can pre-create one as you suggested)?

[karthiknadig]

something remembers what the active env is: is that the Python extension? How can I ask for that inside of activate?

This would be done in your extension using Persistent store or a file. Let us say you have two envs defined in the config prod and dev. Say user by default uses dev. When they want to try prod, they use the UI to set it, set is triggered with project uri and prod env as inputs. You save this information in persistent store (you could use VS code APIs, or some file). Then when get is called you would return prod for the uri. Saving it in persistent store means that when the user exits the IDE, you remember it next time they open it and bring up the state that was expected. Note: If Hatch's way is to restore dev (ie default) environment after IDE reload, that is perfectly fine. In that scenario, you would just keep an in-memory map, and not have the data saved in persisitent store or file.

If you want to see an example for using VS Code persistent store, see setVenvForWorkspace implementation. That is just one way of doing it.

how can I get a list of active Python projects inside of activate in case there’s no env selected for a project (so that I can pre-create one as you suggested)?

The API has a method getPythonProjects that should give you all the projects loaded in the workspace. On first load of your extension, get the projects and internally keep an in-memory map of project uri to environment, and have uris mapped to default envs. You can create the default environment at this point. This should give you good initial state.

[karthiknadig]

@flying-sheep Example for hatch-demo. I just got it working, it seems to list a lot of environments that you could hide or group it in a different way. I will make a PR with what I have.