The PEAK Developers' Center   PythonEggs UserPreferences
 
HelpContents Search Diffs Info Edit Subscribe XML Print View
Version as of 2005-03-22 18:17:03

Clear message


What is a Python Egg

A Python Egg can be used to simplify python distributions. Support may be built in to distutils and the reference python implementation beginning with python 2.5. (There is some support in the Python setuptools sandbox.)

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. (Eggs are to Pythons as Jars are to Java...)

Distribution Format

(Just notes so far)

Package Resource API

The following API routines will be available in the pkg_resources module as module-level functions:

declare_namespace(name)
Declare that the dotted package name name is a "namespace package" whose contained packages and modules may be spread across multiple distributions. The named package's __path__ will be extended to include the corresponding package in all active distributions that contain a package of that name. (More precisely, if an importer's find_module(name) returns a loader, then it will also be searched for the package's contents.) Whenever a Distribution's require() is invoked, it checks for the presence of namespace packages and updates their __path__ contents accordingly. A distribution is "active" if its require() has been invoked, or if it is present on sys.path.
iter_distributions(name=None,path=None)
Searching the list of locations specified by path, yield Distribution instances whose names match name. If name is None, all recognized distributions are yielded. If path is None, the resource manager's default path is searched. If the resource manager has no default path, sys.path is searched. Distribution objects yielded by this routine may be added to sys.metapath in order to make them accessible for importing, as they are PEP 302-compatible "importer" objects.
require(name,version_info=None,path=None)
Ensure that the named distribution (matching version_info if specified) is present on sys.meta_path. The path argument is the same as for iter_distributions(). XXX define version-info format!
resource_string(package_name,resource_name)
Return the named resource as a binary string.
resource_stream(package_name,resource_name,mode='b')
Open the named resource 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 resource_filename() instead.)
resource_filename(package_name,resource_name)
Return a platform file or directory name for the named resource. If the package is in an egg distribution, the resource will be unpacked before the filename is returned. If the named resource is a directory, the entire directory's contents will be extracted before the directory name is returned. Also, if the named resource is an "eager" resource such as a Python extension or shared library, then all "eager" resources will be extracted before the resource's filename is returned. (This is to ensure that shared libraries that link to other included libraries will have their dependencies available before loading.)
set_extraction_path(path)
Set the base path where resources will be extracted to. If not set, this defaults to os.expanduser("~/.python-eggs"). Resources are extracted to subdirectories of this path, named for the corresponding .egg file. You may set this to a temporary directory, but then you must call cleanup_resources() to delete the extracted files when done. (Note: you may not change the extraction path for a given resource manager once resources have been extracted, unless you first call cleanup_resources().)
cleanup_resources(force=False)
Delete all extracted resource files and directories, returning a list of the file and directory names that could not be successfully removed. This function does not have any concurrency protection, so it should generally only be called when the extraction path is a temporary directory exclusive to a single process. This method is not automatically called; you must call it explicitly or register it as an atexit function if you wish to ensure cleanup of a temporary directory used for extractions.

Distribution Objects

These need name, version, python version, and a metadata API, as well as PEP 302 "importer" methods.

require()
Add an appropriate entry to the beginning of sys.meta_path for this Distribution if not present.
get_platform_info()
Return the platform information for this Distribution as a str or None if not present.
get_version_object()
Return the version information for this Distribution as a distutils.version StrictVersion or LooseVersion or None if not present.
get_python_version()
Return the Python version for this Distribution as a str containing the major Python version (i.e. "2.3") or None if not present.
get_name()
Return the name of this Distribution without any platform or version information.
get_archive_name()
Return the name of this Distribution with all platform and version information.
get_distdata(filename, default=NotGiven)
Like PEP 302's get_data, this returns the data for the specified path. This may be used to retrieve distribution metadata (such as EGG-INFO/native_libs.txt). Unlike PEP 302, this method permits you to specify a default value to be returned if the resource is not present in the distribution archive. This is for convenience in retrieving optional metadata files, such as are contained in archives' EGG-INFO files.
get_resource_path(module, package_name, resource_name)

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)
get_resource_stream(module, package_name, resource_name, mode='rb')

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.)

get_resource_filename(module, package_name, resource_name)

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.

get_resource_string(module, package_name, resource_name)
Return the named resource as a binary string.
find_module(fullname, path=None)

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

load_module(fullname)

This method returns the loaded module.

See: PEP 302 Loader Protocol

is_package(fullname)
See: PEP 302 Optional Extensions to the Importer Protocol
get_code(fullname)
See: PEP 302 Optional Extensions to the Importer Protocol
get_source(fullname)
See: PEP 302 Optional Extensions to the Importer Protocol
get_data(filename)
See: PEP 302 Optional Extensions to the Importer Protocol

Implementation

I started doing some of the grunt work for the runtime at:

http://svn.red-bean.com/bob/pyegg/trunk/src/pkg_resources.py

  • BobIppolito

And I've implemented a bdist_egg command as part of the Python "setuptools" sandbox. I've also partially implemented another runtime, modulo the open issues listed below. -- PJE

Open issues:

To-Do:


PythonPowered
EditText of this page (last modified 2005-03-22 18:17:03)
FindPage by browsing, title search , text search or an index
Or try one of these actions: AttachFile, DeletePage, LikePages, LocalSiteMap, SpellCheck