[Tutor] accessing modules found throughout a package?

[Steven D'Aprano]

On Sun, Oct 18, 2015 at 08:07:07AM -0700, Alex Kleider wrote:
> On 2015-10-17 19:49, Steven D'Aprano wrote:
> 
> >which will work from your package's callers, and from within the 
> >package
> >itself provided the top level directory can be found within Python's
> >path. Within the package you can also use relative imports, see the
> >docs for more detail.
> 
> How does one arrange so "the top level directory _can_ be found within 
> Python's path."?

The boring, conventional way is to install the package under 
site-packages.

E.g. if Python is installed here:

/usr/local/lib/python2.7/

(for example), there will also be a directory:

/usr/local/lib/python2.7/site-packages/

If you stick the package directory inside site-packages, it will be 
visible to be imported from Python2.7.

If you install the package using an installer like pip or setuptools, 
chances are it will automatically be placed in the correct 
site-packages. Downside of this is that you need root or admin 
privileges, however starting with Python 2.6, there's also a per-user 
site-packages directory. On Linux systems, that will default to 
something like:

~/.local/lib/python2.7/site-packages/


The less boring way is to adjust your path. There are various ways to do this:

(1) Set an environment variable.

E.g. in my .bashrc file, I have this:

export PYTHONPATH="/home/steve/python/:/home/steve/python/utilities"

which will add the two ":" separated paths to sys.path.

You can launch Python using a specific path like this from bash:

PYTHONPATH="/tmp:$PYTHONPATH" python

(Note that you have to use "" quotes, as bash doesn't evaluate 
environment variables inside '' quotes.)


(2) If you set a PYTHONSTARTUP environment variable giving the path to a 
Python file, you can manipulate the path inside that:

# startup.py
import sys
sys.path.append("something/or/other/")

but be aware that the startup file only runs when you run the 
interactive interpreter directly, it doesn't run when you execute 
scripts.

(3) Of course a module itself can also import sys and manipulate the 
path, but that doesn't help you import the module in the first instance.

(4) If you're distributing an application which happens to be written in 
Python, one nice trick is the make the entry-point to the application 
(the executable file that you run) a shell script which sets up the 
PYTHONPATH environment variable (and any others you need) before calling 
Python. It doesn't have to be a shell script: you can do it in Python as 
well. Since the application script never gets imported, only run 
directly, the bootstrap problem of (3) doesn't matter.

(5) If you're distributing your own Python installation, you can 
hack the values for sys.prefix and sys.exec_prefix, or the site.py file. 
But if you do that, you're on your own.

(6) Create a spam.pth file listing directories to add.

(7) Create a sitecustomize.py or usercustomize.py file.

For (6) and (7), see the documentation for site.py:

https://docs.python.org/2/library/site.html
https://docs.python.org/3/library/site.html



-- 
Steve