py.py shim can break when py and pytest are in different directories in sys.path

[AlexHill]

In pytest 7.2.0, the dependency on pylib was removed and a shim py.py module added. The theory is that if a project needs the real pylib, it'll be installed explicitly, in which case the py/__init__.py package will take precedence over the py.py shim module according to Python's import rules.

However this only works if they're in the same directory. If sys.path contains directories A and B, in that order, where pytest is installed in A and py in B, the shim will be successfully imported from A, and attempts to use the broader functionality of pylib will fail.

This situation occurs when pylib is installed in the system Python environment, and pytest is then installed with pip install --user. An attempt to import e.g. py.io will fail with

>>> import py.io
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'py.io'; 'py' is not a package

Unfortunately pip install --user ... won't help because pylib is technically already installed; the workaround is to use pip install --user --force ....

To reproduce:

Obtain a fresh Python environment with e.g. docker run --rm -it python:3.11 /bin/bash. Then:

root@3beff815cf1a:/# export PIP_ROOT_USER_ACTION=ignore PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_PROGRESS_BAR=off
root@3beff815cf1a:/# pip install py
Collecting py
  Downloading py-1.11.0-py2.py3-none-any.whl (98 kB)
Installing collected packages: py
Successfully installed py-1.11.0
root@3beff815cf1a:/# pip install --user pytest
Collecting pytest
  Downloading pytest-7.2.0-py3-none-any.whl (316 kB)
Collecting attrs>=19.2.0
  Downloading attrs-22.1.0-py2.py3-none-any.whl (58 kB)
Collecting iniconfig
  Downloading iniconfig-1.1.1-py2.py3-none-any.whl (5.0 kB)
Collecting packaging
  Downloading packaging-21.3-py3-none-any.whl (40 kB)
Collecting pluggy<2.0,>=0.12
  Downloading pluggy-1.0.0-py2.py3-none-any.whl (13 kB)
Collecting pyparsing!=3.0.5,>=2.0.2
  Downloading pyparsing-3.0.9-py3-none-any.whl (98 kB)
Installing collected packages: iniconfig, pyparsing, pluggy, attrs, packaging, pytest
  WARNING: The scripts py.test and pytest are installed in '/root/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed attrs-22.1.0 iniconfig-1.1.1 packaging-21.3 pluggy-1.0.0 pyparsing-3.0.9 pytest-7.2.0
root@3beff815cf1a:/# python -c "import py.io"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'py.io'; 'py' is not a package

cc @DrewDevereux

[asottile]

duplicate of #10451