Abstract
This PEP proposes a way to represent the setuptools “entry points”
feature in standard Python metadata. Entry points are a useful
mechanism for advertising or discovering plugins or other exported
functionality without having to depend on the module namespace. Since
the feature is used by many existing Python distributions and not
everyone wants to use setuptools, it is useful to have a way to
represent the functionality that is not tied to setuptools itself.
The proposed feature defines an extension field for the standard
Python distribution metadata and some basic semantics for its use.
Overview
Entry points are represented as an extension in the metadata:
{ …
“extensions”: { “entry_points” : { … } }
}
The extension contains the data in a dictionary format similar to that
accepted by setuptools’ setup(entry_points={}) keyword argument. It is
a dictionary of “group” : [ “key=module.name:attrs.attrs [extra,
extra2, ...]”, ].
“group” is the name of this class of entry points. Values in common
use include “console_scripts” and “sqlalchemy.dialects”. During
discovery, clients usually iterate over all the entry points in a
particular group.
“key” is the name of a particular entry point in the group. It must be
locally unique within this distribution’s group.
“module.name” is the Python module that defines the entry point.
Client code would import the module to use the entry point.
“:attrs.attrs” are the optional attributes of the module that define
the entry point (the module itself can be the entry point). Client
code uses normal attribute access on the imported module to use the
entry point.
“[extra, extra2, ...]” are any optional features of the distribution
(declared with “extras”) that must be installed to use the declared
entry point. This is not common.
Complete example
{ …
“extensions”: { “entry_points” : {
{ “sqlalchemy.dialects” : [ “mysql = sqlalchemy_mysql:base.dialect”] }
} }
}
Use
Client code reads every distribution’s metadata file on sys.path,
filtering for the entry point group name desired, and, if applicable,
the individual entry point name. Once the desired entry point has been
found, a utility function imports the necessary module and attribute
to return an object which can be inspected or called. distlib and
setuptools’ pkg_resources provide APIs for this functionality.
_______________________________________________
Distutils-SIG maillist - Distutils-SIG@python.org
http://mail.python.org/mailman/listinfo/distutils-sig
