[Tutor] still clarifying imorting

[eryksun]

On Mon, May 20, 2013 at 9:43 PM, Jim Mooney <cybervigilante at gmail.com> wrote:
> If I make a package called jimlib with __init__.py in it, and a
> program called bark.py in it, and even put it in site packages, I
> still have to import the program with   import jimlib.bark
>
> But I noticed that the pygraphics package is in site packages, and has
> media.py in it, and all I have to do with that is import media,
> without qualifying it with pygraphics, as in import pygraphics.media
>
> Why don't I have to drill down for media.py as I do with jimlib?

It's using a .pth file named "pygraphics.pth", which should be in your
Lib\site-packages directory on NT. The first and only line is
"pygraphics". This subdirectory is added to sys.path.

Specifically, in the setup.py for PyGraphics, it's using the
"extra_path" argument:

http://code.google.com/p/pygraphics/source/browse/trunk/setup.py#24

This argument is actually undocumented:

http://bugs.python.org/issue901727

To document this a bit, here's a snippet from the distutils source:

            if len(self.extra_path) == 1:
                path_file = extra_dirs = self.extra_path[0]
            elif len(self.extra_path) == 2:
                (path_file, extra_dirs) = self.extra_path
            else:
                raise DistutilsOptionError, \
                      ("'extra_path' option must be a list, tuple, or "
                      "comma-separated string with 1 or 2 elements")

And the function that creates the file:

    def create_path_file (self):
        filename = os.path.join(self.install_libbase,
                                self.path_file + ".pth")
        if self.install_path_file:
            self.execute(write_file,
                         (filename, [self.extra_dirs]),
                         "creating %s" % filename)
        else:
            self.warn("path file '%s' not created" % filename)