Document that `poetry install` modifies PYTHONPATH

• I have searched the issues of this repo and believe that this is not a duplicate.

Issue

Thank you very much for taking some of your valuable time to read this. I hope it’ll be worth it!

What happens?

poetry install with an existing conda environment and src layout silently and permanently adds repo/src to the environment’s PYTHONPATH. This behaviour is not documented (or, I didn’t find it).

$ conda create -n withsrc_py37 python=3.7
$ conda activate withsrc_py37
$ poetry new --src my-src-package
$ cd my-src-package
$ poetry run python -c "import sys, pprint; pprint.pprint(sys.path)"
['',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37\\python37.zip',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37\\DLLs',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37\\lib',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37\\lib\\site-packages']
$ poetry install
$ poetry run python -c "import sys, pprint; pprint.pprint(sys.path)"
['',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37\\python37.zip',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37\\DLLs',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37\\lib',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37',
 'C:\\Users\\THW\\AppData\\Local\\Continuum\\anaconda3\\envs\\withsrc_py37\\lib\\site-packages',
 'c:\\users\\thw\\repos\\my-src-package\\src']  # new!

This change to sys.path persists after conda deactivate and conda activate withsrc_py37.

Why am I surprised?

The idea (for me) with using the src layout is to make it really difficult to run tests against my source code. I want the tests to run against the built and installed package instead, as per hynek and ionelmc.

Making matters more murky, tox’s test environments appear to inherit this PYTHONPATH. This puts the supposedly independent tox runs at risk of using the source code.

Why not a bug?

I don’t know if this is a bug, but I expect not: It seems that there’s no consensus in the community whether the src layout is a good or bad idea, so this behaviour is quite possibly expected for some use cases. And besides, now that poetry is in stable, I guess documenting the current behaviour should come before changing it 😁

Additional details

Output of poetry debug info:

Poetry
Version: 1.0.0
Python:  3.7.5

Virtualenv
Python:         3.7.5
Implementation: CPython
Path:           C:\Users\THW\AppData\Local\Continuum\anaconda3\envs\withsrc_py37
Valid:          True

System
Platform: win32
OS:       nt
Python:   C:\Users\THW\AppData\Local\Continuum\anaconda3\envs\withsrc_py37

What seems to be a highly related PR, “Add src to sys.path if module is in src”: https://github.com/python-poetry/poetry/pull/123

A PR that added documentation for the --src flag: https://github.com/python-poetry/poetry/pull/193

[finswimmer]

Hello everyone,

as written in the docs a poetry install installs the current project in editable mode. This is necessary to be able to run your code immediately after changing it, without going through the cycle “edit file” -> “build package” -> “install package” -> “run command”.

To achieve this poetry uses the path configuration file method described here https://docs.python.org/3/library/site.html

You can avoid installing the package itself by running poetry install --no-root instead.

If you want to make sure your tests are running against the builded packages, your tests should run in an isolated environment as well using e.g. tox. With pytest 6.0 --import-mode importlib was introduced to make sure to run against the builded package. I wrote about it at stackoverflow as well.

fin swimmer

[dedale]

Thanks a lot @thorbjornwolf for creating this issue, I’ve been scratching my head for two hours trying to figure out why in some cases my modules were found and ModuleNotFoundError in other cases.