Stop suggesting direct setting of PYTHONPATH in install instructions

[ketch]

Setting PYTHONPATH directly is considered quite dangerous. For instance,

http://python-notes.curiousefficiency.org/en/latest/python_concepts/import_traps.html

says

Never add a package directory, or any directory inside a package, directly to the Python path.

A similar point is made in this tutorial.

We break this rule in our instructions, e.g. at http://www.clawpack.org/setenv.html#pythonpath.

I think that a lot of problems users run into are caused by this. I propose that we stop supporting or suggesting any installation that requires setting PYTHONPATH. This leaves two options:

• Regular pip install, which puts the Python code into system directories
• In-place pip install ("-e")

Are there objections/counterarguments?

[rjleveque]

@ketch, thanks for these links!

I'm ok with not recommending PYTHONPATH, particularly in view of the various problems pointed out in relation to Python 2 vs. 3.

I personally have still found PYTHONPATH to work fine for what I need, and much easier than pip for my use case where I have several versions for different projects / dual debugging, etc. (and mostly use the Fortran codes rather than pyclaw). But us developers who find this convenient can keep using PYTHONPATH without mentioning it in the install instructions.

[mandli]

Probably not too surprising but I +1 this idea. I think for most people pip install -e is going to be the easiest way to install this and it will result in non-surprising behavior if they modify the python code.

[ketch]

@rjleveque The instructions under http://www.clawpack.org/installing.html#install-from-a-tarfile say to

python setup.py install

in your $CLAW directory, but as far as I understand this is exactly equivalent to running

pip install .

there. Have you found those to give different results?

Later we say

If you installed from a tarfile or using a git clone without using pip, then you will need to set the PYTHONPATH variable...

but this should not be necessary if you did python setup.py install. I'd like to replace python setup.py install with pip install . (or perhaps even better, pip install -e .) in the instructions above so that things are clearer. That will still leave the instructions at http://www.clawpack.org/installing.html#install-other-packages-without-compiling-pyclaw as they are (which means not using pip, and then needing to set the PYTHONPATH). Let me know if you know any reason not to make this change.

[mandli]

With regards to @mjberger's issues with installation I think these are mostly addressed by using a combination of virtualenv and pip install --user. I think there may be a lot of cruft laying around that we could probably remove to get things working more smoothly as well.