Patterns for Loading

this page last updated: 2017-06-28 13:05:57

Patterns for Loading¶

Setuptools entry points are registered as within a namespace that defines the API expected by the plugin code. Each entry point has a name, which does not have to be unique within a given namespace. The flexibility of this name management system makes it possible to use plugins in a variety of ways. The manager classes in stevedore wrap pkg_resources to apply different rules matching the patterns described here.

Drivers – Single Name, Single Entry Point¶

Specifying a driver for communicating with an external resource (database, device, or remote application) is perhaps the most common use of dynamically loaded libraries. Drivers support the abstracted view of the resource so an application can work with different types of resources. For example, drivers may connect to database engines, load different file formats, or communicate with similar web services from different providers. Many drivers may be available for a given application, but it is implied in the interface between the application and the driver that only one driver will be used to manage a given resource.

digraph drivers {
app [label="namespace",shape="record"];
d1 [style=filled,color=".7 .3 1.0",label="driver 1"];
d2 [style=dotted,label="driver 2"];
d3 [style=dotted,label="driver 3"];
app -> d1;
app -> d2 [style=dotted];
app -> d3 [style=dotted];
}

Examples of the drivers pattern include:

database client libraries used by SQLAlchemy
cloud vendor API clients used by libcloud

Hooks – Single Name, Many Entry Points¶

Hooks, signals, or callbacks are invoked based on an event occurring within an application. All of the hooks for an application may share a single namespace (e.g., my.application.hooks) and use a different name for the triggered event (e.g., startup and precommit). Multiple entry points can share the same name within the namespace, so that multiple hooks can be invoked when an event occurs.

$digraph drivers { app [label="namespace::event_name",shape="record"]; l1 [style=filled,color=".7 .3 1.0",label="event_name (lib1)"]; l2 [style=filled,color=".7 .3 1.0",label="event_name (lib2)"]; l3 [style=filled,color=".7 .3 1.0",label="event_name (lib3)"]; app -> l1; app -> l2; app -> l3; }$

Examples of the hooks pattern include:

Emacs mode hook functions
Django signals

Extensions – Many Names, Many Entry Points¶

The more general form of extending an application is to load additional functionality by discovering add-on modules that use a minimal API to inject themselves at runtime. Extensions typically want to be notified that they have been loaded and are being used so they can perform initialization or setup steps. An extension may replace core functionality or add to it.

digraph drivers {
app [label="application",shape="record"];
e1 [style=filled,color=".7 .3 1.0",label="extension 1"];
e2 [style=filled,color=".7 .3 1.0",label="extension 2"];
e3 [style=filled,color=".7 .3 1.0",label="extension 3"];
app -> e1;
app -> e2;
app -> e3;
}

Examples of the extensions pattern include: