Understanding .pth in site-packages

[OKB (not okblacke)]

Josh English wrote:

> Philip,
> 
> Yes, the proper path should be c:\dev\XmlDB, which has the
> setup.py, xmldb subfolder, the docs subfolder, and example
> subfolder, and the other text files proscribed by the package
> development folder. 
> 
> I could only get it to work, though, by renaming the xmldb folder
> in the site-packages directory, and deleting the egg file created
> in the site-packages directory. 
> 
> Why the egg file, which doesn't list any paths, would interfere I
> do not know. 
> 
> But with those changes, the xmldb.pth file is being read.
> 
> So I think the preferred search order is:
> 
> 1. a folder in the site-packages directory
> 2. an Egg file (still unsure why)
> 3. A .pth file

    	You say that the egg file was created by the setup script for the 
library.  Are you sure that this script did not also create or modify a 
.pth file of its own, adding the egg to the path?

    	.pth files do not "redirect" imports from site-packages; they add 
EXTRA directories to sys.path.  Also note that this means the .pth file 
itself is not part of the search path; it's not like you shadow a 
package xyz by creating a .pth file xyz.pth "instead".  A single .pth 
file can list multiple directories, and it's those directories that are 
added to the path.

    	I'm not sure how your package is set up, but easy_install, for 
instance, creates an easy_install.pth file in site-packages.  This file 
contains references to egg files (or, at least in my case, .egg 
directories created by unpacking the eggs) for each package installed 
with easy_install.  As far as I'm aware, Python doesn't have special 
rules for putting egg files in the search path, so my guess is that 
it's something like that: the "setup script" is creating a .pth file (or 
modifying an existing .pth file) to add the egg to the path.

    	Read http://docs.python.org/library/site.html for the description 
of how .PTH files work.  I don't think there is a general way to 
globally "shadow" a package that exists in site-packages.  However, 
according to the docs the .pth files are added in alphabetical order, so 
if it is indeed easy_install.pth that is adding your egg, you could hack 
around it by making a file with an alphabetically earlier name (e.g., 
a_xmldb.pth).

-- 
--OKB (not okblacke)
Brendan Barnwell
"Do not follow where the path may lead.  Go, instead, where there is
no path, and leave a trail."
	--author unknown