The Quick Guide to Python Eggs

PythonEggs - The PEAK Developers' Center

The Quick Guide to Python Eggs

NOTE: If all you want to do is install a project distributed as an .egg file, head straight to the Easy Install page. EasyInstall makes installing Python code as easy as typing easy_install SomeProjectName. You don't need to read this page unless you want to know more about how eggs themselves work.

Table of Contents

• Overview
• Using Eggs
  • Automatic Discovery
• Building Eggs
  • Declaring Dependencies
• Developing with Eggs
  • Running Eggs from Source
  • Accessing Package Resources
• Implementation Status
• Questions

Overview

"Eggs are to Pythons as Jars are to Java..."

Python eggs are a way of bundling additional information with a Python project, that allows the project's dependencies to be checked and satisfied at runtime, as well as allowing projects to provide plugins for other
projects. There are several binary formats that embody eggs, but the most common is '.egg' zipfile
format, because it's a convenient one for distributing projects. All of the formats support including package-specific data, project-wide metadata, C extensions, and Python code.

The easiest way to install and use Python eggs is to use the "Easy Install" Python package manager, which will find, download, build, and install eggs for you; all you do is tell it the name (and optionally, version) of the Python project(s) you want to use.

Python eggs can be used with Python 2.3 and up, and can be built using the setuptools package (see the Python Subversion sandbox for source code, or the EasyInstall page for current installation instructions).

The primary benefits of Python Eggs are:

• They enable tools like the "Easy Install" Python package manager

• .egg files are a "zero installation" format for a Python package; no build or install step is required, just put them on PYTHONPATH or sys.path and use them (may require the runtime installed if C extensions or data files are used)

• They can include package metadata, such as the other eggs they depend on

• They allow "namespace packages" (packages that just contain other packages) to be split into separate distributions (e.g. zope.*, twisted.*, peak.* packages can be distributed as separate eggs, unlike normal packages which must always be placed under the same parent directory. This allows what are now huge monolithic packages to be distributed as separate components.)

• They allow applications or libraries to specify the needed version of a library, so that you can e.g. require("Twisted-Internet>=2.0") before doing an import twisted.internet.

• They're a great format for distributing extensions or plugins to extensible applications and frameworks (such as Trac, which uses eggs for plugins as of 0.9b1), because the egg runtime provides simple APIs to locate eggs and find their advertised entry points (similar to Eclipse's "extension point" concept).

There are also other benefits that may come from having a standardized format, similar to the benefits of Java's "jar" format.