[Python-Dev] Problem with pydoc script in PEP 405 venvs

[R. David Murray]

On Mon, 17 Jun 2013 16:27:45 -0000, Vinay Sajip <vinay_sajip at yahoo.co.uk> wrote:
> Issue #18224 (http://bugs.python.org/issue18224) highlights a problem on
> Windows with the pydoc script provided with venvs created by pyvenv. On
> POSIX, the script is named pydoc and causes no problems: on Windows, it is
> called pydoc.py and this causes problems because it shadows the stdlib pydoc
> module.
> 
> Possible solutions:
> 
> 1. Remove the pydoc script altogether from created venvs, on Windows but
> also on POSIX (for consistency).
> 2. Rename the pydoc script on both Windows and POSIX (e.g. to pydocs.py and
> pydocs respectively).
> 3. Rename the pydoc.py script to pydoc-script.py and introduce a simple .exe
> launcher pydoc.exe adjacent to it (which is how setuptools and distlib
> handle installed scripts).
> 
> The first two approaches are backwards-incompatible, while the third is less
> likely to lead to breakage, but involves adding a Windows script launcher to
> Python. While this is a bigger change, I think any built-in Python installer
> functionality should include such a launcher (as setuptools and distlib do).
> Still, that's probably a discussion for another day.
> 
> Does anyone have any comments? Approach #2 seems the most appropriate. I
> assume it would be reasonable to implement this in both 3.3 and 3.4, as it's
> not a change in core Python APIs.
> 
> In the absence of adverse feedback here, I propose to implement approach #2
> on both 3.3 and 3.4.

I don't think renaming pydoc to pydocs is appropriate on posix.  Too many
people likely have 'pydoc' in their fingers and brains as the command name.

The .bat file suggestion seems better, IMO.

--David