PythonEggs |
UserPreferences |
The PEAK Developers' Center | FrontPage | RecentChanges | TitleIndex | WordIndex | SiteNavigation | HelpContents |
"Eggs are to Pythons as Jars are to Java..."
Python Eggs are zipfiles using the .egg extension, that support including data and C extensions as well as Python code. They can be used with Python 2.3 and up, and can be built using the setuptools package (see http://cvs.sf.net/viewcvs.py/python/python/nondist/sandbox/setuptools/ for source code). Once the implementation is far enough along, we plan to propose it for inclusion with the standard library beginning in Python 2.5.
The primary benefits of Python Eggs are:
There are also other benefits that may come from having a standardized format, similar to the benefits of Java's "jar" format.
To use an egg, simply put its absolute filename in your PYTHONPATH environment variable, or add it to sys.path. That's all. For "pure" (all-Python) eggs, it's just like putting Java .jar files on CLASSPATH.
Some eggs, however, may contain C extensions or need access to non-Python data files contained in the egg. These eggs also need to have access to the pkg_resources module in order to be able to unpack any needed files (like C extensions). So, you need to also make sure you have a setuptools egg on your path for the other egg(s) to work. (See Building Eggs below.)
Note also that only "pure" (all-Python) eggs are platform-independent. Eggs that contain C extensions will have their target platform's name at the end of the filename, just before the .egg, and you will need to make sure that you only use eggs that are appropriate for your platform.
(Note: we are working on a "dependency/discovery" API that will allow programs to automatically find suitable .egg files within specified directories, and recursively find eggs to meet the requested eggs' dependencies. So, in future it should be as simple as pkg_resources.require("SomePackage>=1.2") in order to locate an appropriate .egg and add it to sys.path automatically.)
To build an egg from a package's setup.py, you'll need to have setuptools installed. Just check it out of Python's CVS and run setup.py install to install it. Now you're ready to build eggs.
Edit the target package's setup.py and add from setuptools import setup such that it replaces the existing import of the setup function. Then run setup.py bdist_egg.
That's it. A .egg file will be deposited in the dist directory, ready for use. If you want to add any special metadata files, you can do so in the SomePackage.egg-info directory that bdist_egg creates. There are a handful of special filenames that the egg runtime system understands, like eager_resources.txt, and in the future there will be others to support namespace packages, dependency resolution, etc. These files are copied from the .egg-info directory to an EGG-INFO directory within the egg file, for use by the runtime.
If you want to build eggs from other people's packages (who don't import from setuptools) in Python 2.4 you can do:
python setup.py --command-packages=setuptools.command bdist_egg
In earlier versions of Python you have to copy setuptools/command/bdist_egg.py into lib/pythonX.Y/distutils/command/. This is known to work for Python 2.3.
Note: packages that expect to find data files in their package directories, but which do not use either the PEP 302 API or the pkg_resources API to find them will not work when packaged as .egg files. One way you can check for this is if the .egg file contains data files, and the package is using __file__ to find them. You'll need to then patch the package so it uses pkg_resources.resource_filename() or one of the other resource_* APIs instead of __file__.
Also, some packages (e.g. wxPython) may include dynamic link libraries other than Python extensions. If this is the case, you'll need to create an eager_resources.txt file in the .egg-info directory that lists the in-zip paths to these libraries, one per line. This will let the runtime system know that those files need to be unpacked if any of the extensions are used. Thus, when attempting to import an extension, the runtime will also unpack all the dynamic link libraries that go with it.
(Note: if you still can't get the library to work as an .egg file after trying the above tactics, please report your problem on the distutils-Sig mailing list. Thanks.)
The stuff from here on down is fairly out of date; it's just here to make sure we didn't forget anything once the current runtime refactoring is complete.
The following API routines will be available in the pkg_resources module as module-level functions:
These need name, version, python version, and a metadata API, as well as PEP 302 "importer" methods.
For a module that this Distribution controls, return the path for the given resource. Typically implemented as:
return os.path.join(os.path.dirname(module.__file__), resource_name)
Open the path as a file-like object, using the specified mode ('t', 'b', or 'U').
(Note that this does not necessarily return an actual file; if you need a fileno() or an actual operating system file, you should use get_filename() instead.)
Return an openable file or directory path for the given filename. If the filename is not already on the filesystem, it will be extracted to a file allocated by the ResourceManager. If the filename represents a directory, the ResourceManager will allocate files for the entire tree.
The Distribution may allocate more files than requested during this call. A trivial implementation could extract the entire archive's contents, and a complex implementation may decide to extract all object code at the same time (e.g. dll, pyd, so, etc.). Resources that are extracted before they are requested are termed "eager" resources.
This method will be called with the fully qualified name of the module. If the importer is installed on sys.meta_path, it will receive a second argument, which is None for a top-level module, or package.__path__ for submodules or subpackages. It should return a loader object if the module was found, or None if it wasn't. If find_module() raises an exception, it will be propagated to the caller, aborting the import.
See: PEP 302 Importer Protocol
This method returns the loaded module.
See: PEP 302 Loader Protocol