Explain Python entry points?

Question

I've read the documentation on egg entry points in Pylons and on the Peak pages, and I still don't really understand. Could someone explain them to me, or point me at an article or book that does?

Answer 1

What context are you planning on using these Python scripts in? If it's the context of a web application, you want to read about WSGI, the gateway interface that handles moving HTTP calls to Python egg calls.

Answer 2

From abstract point of view, entry points are used to create a system-wide registry of Python callables that implement certain interfaces. There are APIs in pkg_resources to see which entry points are advertised by a given package as well as APIs to determine which packages advertise a certain entry point.

Entry points are useful for allowing one package do use plugins that are in another package. For instance, Ian Bicking's Paste project uses entry points extensively. In this case, you can write a package that advertises its WSGI application factory using the entry point paste.app_factory.

Another use for entry points is enumerating all the packages on the system that provide some plugin functionality. The TurboGears web framework uses the python.templating.engines entry point to look up templating libraries that are installed and available.

Answer 3

An "entry point" is a function (or other callable function-like object) that a developer or user of your Python package might want to use.

The most popular kind of entry point is the "console_script" entry point, which points to a function that you want made available as a command-line tool to whoever installs your package. I have a package I've just deployed called "cursive.tools", and I wanted it to make available a "cursive" command that someone could run from the command line, like:

$ cursive --help
usage: cursive ...

The way to do this is define a function, like maybe a "cursive_command" function in cursive/tools/cmd.py that looks like:

def cursive_command():
    args = sys.argv[1:]
    if len(args) < 1:
        print "usage: ..."

and so forth; it should assume that it's been called from the command line, parse the arguments that the user has provided, and ... well, do whatever the command is designed to do.

Install the docutils package for a great example of entry-point use: it will install something like a half-dozen useful commands for converting Python documentation to other formats.