It takes a simple approach: you tell it what the requirements are and Eco fetches and installs those packages in a single directory, independent from your global Python installation. It is designed for projects that should just work when you type PYTHONPATH=./eco/lib python. However, a script to do this is created for you as ./eco/bin/python (read the scripts section for more info).

Eco is a wrapper around pip but is less functional than pip. Long live pip!

Eco requires both pip and setuptools; eco itself can be run after installation with the eco script or can be run from source as /path/to/eco-source/eco.py. Currently, eco is only available from source, so check out the code and do:

$ cd eco-source
$ sudo python setup.py install

You should now be able to run:

$ eco --help

And if you have neither pip nor setuptools, preface the above command with:

Since you typically want to work with your module the same way a user would, Eco will automatically read module requirements from a setup.py file. Note that specifying requirements in setup() is only supported by setuptools. If a setuptools-enabled setup.py file exists in the directory you run Eco from, Eco will inspect its keyword arguments to determine the requirements for your project. Here is an example:

Eco will look for two config files in your working directory, setup.cfg and eco.cfg. If either of those exist then the name / value pairs in the [eco] section will be used as default values for command line options. If both files exist, they will both be parsed but options declared in eco.cfg will take precedence.

Here is an example of setting a custom value for --index-url, --eco-lib, and --eco-bin

Eco assumes you only want to build modules that do not already exist in your sys.path. That way you can install hard to build modules once for all projects and use separate ecosystems in each project for custom versions of modules. Alternatively, if you want to ignore already installed modules when resolving requirements, specify --ignore-sys.

To create a WSGI compatible script that uses modules inside your ecosystem, define an [eco.wsgi_scripts] section in either eco.cfg or setup.cfg like this

[eco.wsgi_scripts]
blog.wsgi = my_blog:application

This would create a script named ./eco/bin/blog.wsgi that would execute from my_blog import application which can be handled by mod_wsgi or any other WSGI server container. If the name after the colon is not named application it will be aliased as such for WSGI compatibility.

For projects that are already using setuptools entry points for creating scripts, Eco will make a valiant attempt to patch the auto-generated scripts so that they work as expected in your local ecosystem. Obviously, Eco does not patch any global scripts you installed with pip or easy_install.

Eco is a bit like virtualenv but it has less features. The key differences are that eco puts all modules in one directory and there are no symlinks to system modules. This makes it possible to manage eco directories in version control or to zip them for Google App Engine, etc. Eco also makes project setup as simple as running the eco command without any arguments. There are some virtualenv wrappers that also make setup simple; paver is one worth considering for your own needs.

You will get caught in a near infinite loop if you try to build an ecosystem that depends on PasteDeploy (i.e. for a Pylons app). This is due to Paste's entry_points. There is a patch to pip in http://bitbucket.org/kumar303/pip/ but it is a little intrusive since it uses addsitedir(). It has not been accepted into pip yet and will probably need to become less intrusive before that happens. You will need to install this fork of pip to fix the problem.

Eco forces you to keep a clean global site-packages. In other words, if you require version 1.2 of SomeModule in your ecosystem but you have 1.1 installed in your global site-packages then eco will not build an ecosystem until you have removed the 1.1 egg. This is a side effect of using addsitedir() to make setuptools work within an ecosystem. Until someone convinces me otherwise, I consider it a feature ;)

Using development eggs in eco is hard. You have to copy over TheModule.egg-info directory from the source into eco/lib (you don't have to copy over the module). Maybe this will be improved.