Reproduced from

• Python eggs - a Simple Introduction

To understand Python egg, you need to understand the Python's way of organizing code files.

Module

The basic unit of code reusability in Python: a block of code imported by some other code. It is most often a module written in Python and contained in a single .py file. Also called a script.

Let us say that the file hello.py contains a function:

# `hello.py`
def hello_world():
  print('Hello World)

Then it is possible to import that function like this: (import from .py file)

from hello import hello_world

Package

A module that contains other modules; typically contained in a directory in the filesystem and distinguished from other directories by the presence of a file __init__.py.

A step up from a script is a module, which is a library with an __init__.py file in it.

hello/
  __init__.py

You can then put the hello_world function into the __init__.py script, and import it as you did before: (import from package)

from hello import hello_world

You could also keep it in the hello.py file from before.

hello/
  __init__.py
  hello.py

But then you must import it like this:

from hello.hello import hello_world

Unless you import it into the module namespace. You do this in the __init__.py script:

from hello import hello_world

Then you will once more be able to write:

from hello import hello_world

This ensures you can reorganize your code and still remain backward compatibility.

You can have modules inside modules. A python library is just a module or a structure of modules.

A structure of modules is called a package.

Distutils

So far it has all been about writing and organizing Python code. But the next step is the distribution of said code. The first step in this direction is distutils.

Distutils was written to have a single unified way to install Python modules and packages. Basically, you just cd to the directory of the module and write:

python setup.py install

Then the module will automagically install itself in the python it was worked with.

Distutiles defines a directory/file structure outside you modules, that has nothing to do with the module per se but is used to distribute the module.

If you want to make a distribution of the hello module you must put it inside a directory that also contains a setup.py file.

somedir/
  setup.py
  hello/
    __init__.py
    hello.py

The setup.py could contain this code, that runs the setup function:

from distutils.core import setup

setup(
  name='hello',
  version='1.0',
  packages=['hello',],
)

You then run the code like this:

python setup.py sdist

And it will create a new directory structure like this:

somedir/
  setup.py
  hello/
    __init__.py
    hello.py
  dist/
    hello-1.0.tar.gz

The hello-1.0.tar.gz then contains the package distribution. It has this structure when unpacked:

hello-1.0/
  PKG-INFO
  setup.py
  hello/
    __init__.py
    hello.py

The hello package is inside it. It is just a copy of your own package with no changes.

setup.py is here too. It is also just a copy of the one you wrote to create the package with. The clever thing about distutils is that it can use the same script to create the distribution as it uses to install the package.

PKG-INFO is a new file and it just contains some metadata for the package. Those can be set in the setup.py.

Setuptools

Setuptools is built on top of distutils. It makes it possible to save modules in pypi, or somewhere else. It uses eggs for distribution.

eggs

An egg is created very much like a distutil package. You just have to change a line in your setup.py.

from setuptools import setup  # this is new
setup(
  name='hello',
  version='1.0',
  packages=['hello',],
)

Then you call it with:

python setup.py bdist_egg

And you get a new file in your dist directory:

dist/
  hello-1.0-py2.4.egg

This is the egg that you can put on your website, or even better, publish to pypi. You can get an account on pypi, and then you will be able to add your eggs via the command line like:

setup.py bdist_egg upload

Easy Install

When you have uploaded your egg, all the world is able to use it installing it with easy_install:

easy_install hello

Easy install with then find the egg on pypi, download it, compile if necessary and add it to your sys.path so that Python will find it.

Buildout

Buildout is a configuration based system for making complicated but repeatable setups for large systems.
Phew. That sounds complicated. Well, buildout can be. But what is interesting from an eggs based point of view is that you configure what eggs are to be installed in your system.
Inside your buildout.cfg you can have a line like:

eggs = 
  hello

The buildout will automatically download and install the hello package in your system.

Buildout can themselves be distributed as eggs, and you can extend a buildout to add a new package. This is how you can install a Plone buildout and then add your own packages to it. Basically creating your own custom Plone distributions.