Where To Place Your Own Modules - Page 5

In the example that started this chapter, the mymathmodule was accessible to Python because: (1) when you execute Python interactively, the first element of sys. path is "", telling Python to look for modules in the current directory; and (2) you were executing Python in the directory which contained the mymath.py file. In a production program, neither of these conditions will typically be true. You will not be running Python interactively, and Python code files will not be located in your current directory. In order to ensure that modules coded by you can be used by your programs, you need to do one of the following:

• Place your modules into one of the directories that Python normally searches for modules.
• Place all of the modules used by a Python program into the same directory as the program.
• Create a directory (or directories) which will hold your modules, and modify the sys.path variable so that it includes this new directory.

Of these three options, the first is apparently the easiest, and is also an option that should never be chosen because it can cause trouble. For example, what if you place new modules in a standard Python directory, and then you or someone else installs a new version of Python on top of that? Your modules would disappear and your programs would stop working, even if a new installation were done more carefully and you still had the old directory with your modules. You would still have to remember which ones are yours and copy them to their new residence.

Note that it's possible that your version of Python includes local code directories in its default module search path. Such directories are specifically intended for site-specific code, and are not in danger of being overwritten by a new Python install, because they are not part of the Python installation. If your sys.path refers to such directories, put your modules there.

The second option is a good choice for modules that are associated with a particular program. Just keep them with the program.

The third option is the right choice for site-specific modules that will be used in more than one program at that site. You can modify sys.path in various ways. You can assign to it in your code, which is easy, but hard-codes directory locations right into your program code; you can set the PYTHONPATH environment variable, which is relatively easy, but may not apply to all users at your site; or you can add to the default search path using using a .pth file.

See the section on environment variables in the appendix for examples of how to set PYTHONPATH. The directory or directories you set it to are prepended to the sys.path variable. If you use it be careful that you do not define a module with the same name as one of the existing library modules that you are using or is being used for you. Your module will be found before the library module. In some cases this may be what you want, but probably not often.

You can avoid this issue using the .pth method. In this case, the directory or directories you added will be appended to sys.path. The last of these mechanisms is best illustrated by a quick example. On Windows you can place this in the directory pointed to by sys.prefix. Assume your sys.prefix is c:\program files\python, and you place the following file in that directory.

mymodules
c:\ My Documents\ python\ modules

Then the next time a Python interpreter is started, sys. path will have c:\program files\python\mymodules and c:\My Documents\python\modules added to it, if they exist. You can now place your modules in these directories. Note that the mymodules directory still runs the danger of being overwritten with a new installation. The modules directory is safer. You also may have to move or create a mymodules. pth file when you upgrade Python. See the description of the site module in the Python Library Reference if you want more details on using .pth files.

Private names in modules

We mentioned that you could say from module import * to import almost all names from a module. The exception to this is that names in the module beginning with an underscore cannot be imported in this manner. The primary use of this intentional feature in Python is to permit people to write modules which are intended for importation with from module import *. By leading off all internal names (i. e., names which should not be accessed outside the module) with an underscore, the module writer can ensure that from module import * brings in only those names which the user will want to access.

To see this in action let's assume we have a file called modtest. py, containing the following code:

""" modtest: our test module"""
def f( x):
  return x

def _g( x):
  return x

a = 4
_b = 2

Now, start up an interactive session, and try the following:

>>> from modtest import *
>>> f( 3)
3
>>> _g( 3)
Traceback (innermost last):
  File "< stdin>", line 1, in ?
NameError: _g
>>> a
4
>>> _b
Traceback (innermost last):
  File "< stdin>", line 1, in ?
NameError: _b

As you can see, the names f and awere imported, but the names _g and _b remain hidden outside of modtest. Note that this behavior occurs only with from … import *. We can do the following to access _g or _b:

>>> import modtest
>>> modtest._ b
2
>>> from modtest import _g
>>> _g( 5)
5

The convention of leading underscores to indicate private names is used throughout Python, and not just in modules. You'll encounter it in classes and packages, later in the book.

The Import Statement - Page 4
The Quick Python Book
Library and Third-Party Modules - Page 6