Regression: `venv` virtual environments not providing `pydoc`

[Athanasius]

Bug report

Bug description:

I started a new python project today and naturally did this within a venv virtual environment. Hitting some frustration on not seeing any documentation on the web pages for the modules I was utilising I turned to pydoc, but it found nothing. On checking the actual installed files for the modules they did have docstrings.

python -m pydoc ... worked properly.

Upon checking which pydoc pointed out I was still using the system pydoc, which would of course have no knowledge of the venv library path in order to look inside it for relevant documentation.

I found https://github.com/python/cpython/issues/59362 from 2012, which claims to have address this, so this is clearly a regression, but I've no idea when it was introduced.

I'm doing all of this on a Debian bookwork 12.5 system which is up to date. I've rested using a pyenv installed Python 3.12.3. I also have no pydoc in <venv>/Scripts on Windows (with Python from python.org installers) venvs.

1. Set up pyenv using latest from https://github.com/pyenv/pyenv.git
2. Ensure it's active, i.e. setting PATH and PYENV_ROOT, then performing shell initialisation.
3. pyenv install 3.12.3
4. pyenv local 3.12.3 and confirm with which python and python --version that it's using it.
5. python -m venv venv-no-pydoc

These are the contents:

15:27:36 0$ ls -al venv-no-pydoc/bin/
total 44
drwx------ 2 athan athan 4096 Apr 14 15:27 ./
drwx------ 5 athan athan 4096 Apr 14 15:27 ../
-rw-r--r-- 1 athan athan 9033 Apr 14 15:27 Activate.ps1
-rw-r--r-- 1 athan athan 2064 Apr 14 15:27 activate
-rw-r--r-- 1 athan athan  941 Apr 14 15:27 activate.csh
-rw-r--r-- 1 athan athan 2220 Apr 14 15:27 activate.fish
-rwxr-xr-x 1 athan athan  245 Apr 14 15:27 pip*
-rwxr-xr-x 1 athan athan  245 Apr 14 15:27 pip3*
-rwxr-xr-x 1 athan athan  245 Apr 14 15:27 pip3.12*
lrwxrwxrwx 1 athan athan   43 Apr 14 15:27 python -> /usr/local/pyenv/versions/3.12.3/bin/python*
lrwxrwxrwx 1 athan athan    6 Apr 14 15:27 python3 -> python*
lrwxrwxrwx 1 athan athan    6 Apr 14 15:27 python3.12 -> python*

I've worked around the issue in my project venv by setting up .venv/bin/pydoc with contents:

#!/usr/local/src/fysh-geoip-country/maxmind-geoip-country/.venv/bin/python
# -*- coding: utf-8 -*-

import pydoc
import sys

sys.path.append('/usr/local/src/fysh-geoip-country/maxmind-geoip-country/.venv/lib')
if __name__ == '__main__':
    pydoc.cli()

Using the full path on the #! line is how the provided pip script is set up, so there's no reason that the same code that achieves that couldn't also include the sys.path.append(...) line, or other equivalent to ensure pydoc knows about the path.

CPython versions tested on:

3.12

Operating systems tested on:

Linux

[Athanasius]

Actually, that hacked together pydoc isn't always working either. Having looked at some of the code I fear that something is undoing the addition to sys.path.

It works if I .venv/bin/pydoc geoip2.errors, but not with plain pydoc geoip2.errors, despite which pydoc citing that venv path.

[Athanasius]

Someone else-net has pointed out https://github.com/pypa/virtualenv/pull/265

[Athanasius]

A workaround is:

cp -p /usr/bin/pydoc<version> .venv/bin
$EDITOR .venv/bin/pydoc<version>
# Change the #! line to be the same as in .venv/bin/pip

# Now one of:
cp -p .venv/bin/pydoc<version> .venv/bin/pydoc
# Or alternatively
cd .venv/bin
ln -s pydoc<version> pydoc

i.e. ensuring the #! line points to the venv python is sufficient, no need to mess with sys.path directly.