fd4e42f0fe
Expand and reorg the naming discussion. Add a section on the mechanics of creating plugins, with some tested example code. Signed-off-by: Doug Hellmann <doug.hellmann@dreamhost.com>
1.9 KiB
Guidelines for Naming Plugins
Stevedore uses setuptools entry points to define and load plugins. An entry point is standard way to refer to a named object defined inside a Python module or package. The name can be a reference to any class, function, or instance, as long as it is created when the containing module is imported (i.e., it needs to be a module-level global).
Names and Namespaces
Entry points are registered using a name in a namespace.
Entry point names are usually considered user-visible. For example, they frequently appear in configuration files where a driver is being enabled. Because they are public, names are typically as short as possible while remaining descriptive. For example, database driver plugin names might be "mysql", "postgresql", "sqlite", etc.
Namespaces, on the other hand, are an implementation detail, and
while they are known to developers they are not usually exposed to
users. The namespace naming syntax looks a lot like Python's package
syntax (a.b.c) but namespaces do not correspond to
Python packages. Using a Python package name for an entry point
namespace is an easy way to ensure a unique name, but it's not required
at all. The main feature of entry points is that they can be discovered
across packages. That means that a plugin can be developed and
installed completely separately from the application that uses it, as
long as they agree on the namespace and API.
Each namespace is owned by the code that consumes the plugins and is
used to search for entry points. The entry point names are typically
owned by the plugin, but they can also be defined by the consuming code
for named hooks (see ~stevedore.hook.HookManager). The names of entry
points must be unique within a given distribution, but are not
necessarily unique in a namespace.