`venv.EnvBuilder.ensure_directories` returns incorrect `inc_path` value

[FFY00]

Bug report

Bug description:

$ ./python
Python 3.14.0a2+ experimental free-threading build (heads/main:79b7cab50a3, Dec  7 2024, 19:01:51) [GCC 14.2.1 20240910] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import venv
>>> builder = venv.EnvBuilder()
>>> context = builder.ensure_directories('venv')
>>> context.inc_path
'venv/include/python3.14td'

$ venv/bin/python
Python 3.14.0a2+ experimental free-threading build (heads/main:79b7cab50a3, Dec  7 2024, 19:01:51) [GCC 14.2.1 20240910] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import sysconfig
>>> sysconfig.get_path('include')
'/usr/local/include/python3.14td'

I noticed this when looking at the venv code:

cpython/Lib/venv/__init__.py

Lines 102 to 109 in 79b7cab

	def _venv_path(self, env_dir, name):
	vars = {
	'base': env_dir,
	'platbase': env_dir,
	'installed_base': env_dir,
	'installed_platbase': env_dir,
	}
	return sysconfig.get_path(name, scheme='venv', vars=vars)

As the name suggests, installed_base and installed_platbase should be pointing to the base installation, not the virtual environment.

Note: The include directory being shared between all environments in a Python installation is a known issue.

CPython versions tested on:

CPython main branch

Operating systems tested on:

No response

Linked PRs

• GH-127724: don't use sysconfig to calculate the venv local include path #127731

[FFY00]

The code mentioned above was introduced in GH-31034, but it sort-of matches what the original code, so I didn't catch it when reviewing that PR. The previous code goes back to 7ded1f0, which is the original venv implementation.

I believe the motivation for this is described by PEP 405's "include files" section, which says we should create a {venv_prefix}/include directory, and symlink {venv_prefix}/include/pythonX.X to {base_prefix}/include/pythonX.X, but it seems this was never implemented.

Currently, we just create the directory, but we don't symlink anything. Before GH-31034, we only created {venv_prefix}/include, now we create {venv_prefix}/include/pythonX.X.

We could adjust the implementation to match PEP 405, but that would require moving the include/platinclude sysconfig paths from installed_base/installed_platbase to base/platbase, which would break existing virtual environments. Though, minor version updates change the purelib/platlib paths, so existing virtual environments essentially get "reset", so there is already some expected amount of breakage. That said, some users will still re-use the old environment, which, if we do the mentioned include paths changes, would result in a include directory that doesn't have headers. To deal with this, we could issue a warning at startup.

[FFY00]

Nevermind, this follows PEP 405. It would be helpful to add a comment explaining this in the code.

It could also be helpful to explain this in the documentation, though, after moving away from distutils, nobody seems to be utilizing the weird venv-specific include directory. The proposal in GH-88611 would effectively standardize this directory, but with GH-103481 planned, and since this does not seem to be causing any major issues downstream, I think it may be best to just leave it as-is for now.