Documentation: With system python, recommend installing a homebrew.pth instead of setting PYTHONPATH

[NikolausDemmel]

In the discussion about bottling python bindings (#27112), @minrk suggested to use a homebrew.pth file instead of setting the (evil) PYTHONPATH variable. This should be suggested to be used in combination with system python on the wiki [1], independent of witch python (system/brewed) homebrew decides to recommend (see #27137).

system Python requires you to set the PYTHONPATH, which I think is horrible.

This isn't quite accurate, I've never used PYTHONPATH. I include homebrew site-packages by adding a homebrew.pth to ~/Library/Python/2.7/lib/python/site-packages/homebrew.pth (you can use /Library/ instead of ~/Library/ if you want it system-wide):

echo "$(brew --prefix)/lib/python2.7/site-packages" > ~/Library/Python/2.7/lib/python/site-packages/homebrew.pth

Does such a homebrew.pth file in /Library/ or ~/Library/ play nice with brewed python, or would it create some conflict? I guess it should be fine (albeit unnecessary), right?

[1] https://github.com/Homebrew/homebrew/wiki/Homebrew-and-Python

[daviewales]

I thought there might be conflicts if a library built with Python 2.7.6 was imported by Python 2.7.5, but preliminary testing has not shown any problems. I'm still suspicious, however.

I would word the message something like this:

If you need to use Homebrew Python bindings with system Python, run
echo "$(brew --prefix)/lib/python2.7/site-packages" > ~/Library/Python/2.7/lib/python/site-packages/homebrew.pth

Incidentally, I find that the path ~/Library/Python/2.7/lib/python/site-packages doesn't exist by default on my system.

[NikolausDemmel]

If we recommend system python by default (see #27137), the wording should be less passive.

Consider these recommendations to be used by the novice user who just wants to install some python stuff as dependecies. Possibly sastifying those dependencies was the reason to install homebrew to begin with. He does not know what he wants or what he needs. She wants to make stuff work.

[daviewales]

But if we want to make stuff work, we would just recommend brewed Python...

[MikeMcQuaid]

Let's keep the brewed vs system Python conversation in #27137 or, ideally, #27112.

[daviewales]

Good point. Sorry.

[MikeMcQuaid]

PR for this in #27329.

[NikolausDemmel]

Great stuff. We need to also update the wiki once all the recent python changes have settled.

[NikolausDemmel]

I hate to be a nitpick, but could we have this info on the "Homebrew and Python" wiki as well? Possibly in the "site-packages and PYTHONPATH" section. It should recommend to use

mkdir -p ~/Library/Python/2.7/lib/python/site-packages
echo "$(brew --prefix)/lib/python2.7/site-packages" >> ~/Library/Python/2.7/lib/python/site-packages/homebrew.pth

instead of setting PYTHONPATH when using system python with brewed python modules.

I would edit it myself, but I can't :-/.

[MikeMcQuaid]

This is output when you install something that installs Python modules and don't already have it set.

[NikolausDemmel]

Yes I realize that and that is very good. But I see the wiki as place to sum up how things tie together independent from what I may or may not have installed. For example, it should tell me what are the differences when using system python while I currently have brewed python installed. Do you see any reason not to have this info on the wiki?

[MikeMcQuaid]

This sort of documentation gets outdated really quickly. Ideally most of our documentation would be replaced with responding to user events.

[NikolausDemmel]

I guess I have a different opinion. Response to user events are extremely useful, in particular if people just do one thing at a time, e.g. install this one formula.

But "traditional" documentation is also invaluable. With only having user event type documentation, it is virtually impossible for an outsider to get an overview of what is going on, since he would have to trigger all the events to get at the documentation, or read all the code. Hardly a practical way for getting an overview. For example if I want to recommend to people to use homebrew for something which involves python, I can not only consider what happens when I install a formula on my machine with my particular setup.

I agree that outdated documentation is also an issue and in an ideal world you would fuel both types of documentation from a common source. However what is the point of having the wiki page if it only tells you half the story. I think the wiki documentation is fine as it is, as long as it gets the occasional small update as homebrew evolves.

I will stop arguing after this post, but IMHO one way or another the "site-packages and PYTHONPATH" section on that wiki page should be updated, as it does not say anything output PYTHONPATH.