hatch/vscode integration

[grst]

Hi @flying-sheep,

I'm working on improving the template docs in #406.

One point I'm struggling with is the integration of hatch and vscode because it's not as smooth as I'd like.

Even if I manage to get vscode to discover the default hatch env as described here,
this refers to the "default" (dev) environment. However, for running tests, we need the .[test] "extra" dependencies included in the hatch-test environment.

How do you typically set this up in vscode?

I was wondering if it makes our lives easier to not separate between the test and dev dependency groups. After all "testing" is part of the dev workflow.

cookiecutter-scverse/{{cookiecutter.project_name}}/pyproject.toml

Lines 30 to 53 in 45df5b4

	optional-dependencies.dev = [
	"pre-commit",
	"twine>=4.0.2",
	]
	optional-dependencies.doc = [
	"docutils>=0.8,!=0.18.*,!=0.19.*",
	"ipykernel",
	"ipython",
	"myst-nb>=1.1",
	"pandas",
	# Until pybtex >0.24.0 releases: https://bitbucket.org/pybtex-devs/pybtex/issues/169/
	"setuptools",
	"sphinx>=8.1",
	"sphinx-autodoc-typehints",
	"sphinx-book-theme>=1",
	"sphinx-copybutton",
	"sphinx-tabs",
	"sphinxcontrib-bibtex>=1",
	"sphinxext-opengraph",
	]
	optional-dependencies.test = [
	"coverage",
	"pytest",
	]

[flying-sheep]

Yeah, really annoying timeline issue:

1. I contributed the hatch env discovery to VS Code Python
2. VS Code Python froze its env discovery code, encouraging people to make extensions instead
3. Hatch introduced its internal envs (e.g. hatch-test), which need a -i option for hatch env show to list them

So we can’t fix this in VS Code Python (since they froze their code) and making the standalone extension is really hard since you need to do so many things manually: https://github.com/flying-sheep/vscode-hatch/

I’ve been asking some questions in here: microsoft/vscode-python-environments#378 but someone would have to really understand how that API is supposed to work to implement things correctly

If someone finishes that extension, the advantage would be that it could do cool things like actually creating/syncing the environments when switching to them, leading to a really nice integrated experience.

How do you typically set this up in vscode?

cumbersomely:

1. hatch test to create the env
2. hatch env find hatch-test
3. triple-click the line representing the env I want to use, Ctrl-C
4. Ctrl-Shift-P "interp" to get the “Select Interpreter” action
5. “Enter interpreter path” then Ctrl-V

[grst]

Ok, then a hatch vscode extension would be the way to go, but I can see how this isn't trivial. Aren't the hatch maintainers interested in working on that? Seems like a major pain point of their tool given that vscode is one of the most popular editors.

What do you think regarding

I was wondering if it makes our lives easier to not separate between the test and dev dependency groups. After all "testing" is part of the dev workflow.

[flying-sheep]

Aren't the hatch maintainers interested in working on that?

I’m going to ask in the PyPA discord, good idea.

I was wondering if it makes our lives easier to not separate between the test and dev dependency groups. After all "testing" is part of the dev workflow.

My idea for dev is

1. CLI tools (so users have them available even if they didn’t install them globally)
2. type stubs (e.g. scipy-stubs) for better type hints while developing
3. other stuff like adding ipykernel so an env can be used as notebook kernel

so basically goodies that you always want to be active when developing locally. Ideally it’d be excluded from CI but it doesn’t really matter that it’s installed in CI.

[grst]

Ok, then how about to keep them separate, but make the hatch default env include both test and dev?

[flying-sheep]

Hmm maybe, I can think of two issues:

• Other envs inherit from default: I wouldn’t want pytest, pytest-xdist, pytest-rerunfailures, coverage, and all their deps in my docs env, but it’s not a big deal.

• More importantly if we do that, hatch test won’t run in the same environment that’s going to be used by VS Code’s test runner, so if the envs contain different dep versions, confusing breakage could happen in one case and not the other.

  So maybe with a big red warning box that informs users about this?

[grst]

So maybe with a big red warning box that informs users about this?

I would prefer to use what's the best solution moving forward should a fully-featured hatch vscode extension exist and describe workarounds to find the correct environment in the meanwhile.

With that in mind, what would be the correct environment (and what should it contain) to be used as "Python interpreter" in vscode (or any other IDE)? I think it would need to contain both dependency groups either way, because you need all the pytest stuff to develop your testing code and you need the type stubs for developing the main project. You'll also want to have CLI tools installed because the corresponding env will also be activated in the terminal.

Other envs inherit from default: I wouldn’t want pytest, pytest-xdist, pytest-rerunfailures, coverage, and all their deps in my docs env, but it’s not a big deal.

Hmm, I also don't think the docs env would need the other "dev" dependencies, such as CLI tools. Is it not possible to isolate the docs env entirely?

More importantly if we do that, hatch test won’t run in the same environment that’s going to be used by VS Code’s test runner, so if the envs contain different dep versions, confusing breakage could happen in one case and not the other.

Would it be better then to get rid of dev entirely and merge everything in test? Or like this?

[tool.hatch.envs.default]
installer = "uv"
features = [ "test", "dev" ]

[tool.hatch.envs.hatch-test]
features = [ "test", "dev" ]

[flying-sheep]

With that in mind, what would be the correct environment (and what should it contain) to be used as "Python interpreter" in vscode (or any other IDE)?

Whatever you’re working on. Especially with the extension, it should be trivial to switch.

General development? hatch-test.py3.13
Fixing a backwards compat bug? hatch-test.py3.11
Working on the doc building process? docs

Is it not possible to isolate the docs env entirely?

Yes! See inheritance, specifically self-referential environments

[tool.hatch.envs.docs]
template = "docs"
installer = "uv"  # has to be repeated then
...

More importantly if we do that, hatch test won’t run in the same environment that’s going to be used by VS Code’s test runner, so if the envs contain different dep versions, confusing breakage could happen in one case and not the other.

Would it be better then to get rid of dev entirely and merge everything in test?

The issue I mean is that if you use default to run tests from VS Code and hatch-test.py.3.13 to run tests from CLI, the envs can easily slightly differ (say, they have been created on a different day and contain different dep versions)

[flying-sheep]

Like I’m open to do stuff differently than we do them in anndata/scanpy, but I want to avoid situations where people get confused and don’t get to benefit from the advantages of isolation and reproducibility between CI and local that Hatch offers.

[grst]

Whatever you’re working on. Especially with the extension, it should be trivial to switch.

General development? hatch-test.py3.13
Fixing a backwards compat bug? hatch-test.py3.11
Working on the doc building process? docs

That makes sense, but at least in the first two cases, you would want to have the "dev" dependencies (type stubs in your example) to be installed.

The issue I mean is that if you use default to run tests from VS Code and hatch-test.py.3.13 to run tests from CLI, the envs can easily slightly differ (say, they have been created on a different day and contain different dep versions)

What would be an actual use-case for default then? Given what you wrote it seems to me that hatch-test.py.3.13 would be a much better default environment.

Like I’m open to do stuff differently than we do them in anndata/scanpy, but I want to avoid situations where people get confused and don’t get to benefit from the advantages of isolation and reproducibility between CI and local that Hatch offers.

I'm fully with you here that we should take advantage of these features. I just want to figure out reasonable defaults for most of our users that create minimal overhead, especially when working on smaller projects.

See #426 for a suggestion.

[flying-sheep]

at least in the first two cases, you would want to have the "dev" dependencies (type stubs in your example) to be installed.

yeah, that’s what I meant with “install the dev dependencies into every environment you use for local development”

What would be an actual use-case for default then?

maybe if your project has a CLI, you could use it to run scripts? It does have the most elegant syntax for that: hatch run myscript