/ironfroggy-straight.plugin-57ef11c/ironfroggy-straight.plugin-57ef11c/README

 1# straight.plugin
 2
 3straight.plugin is a Python plugin loader inspired by twisted.plugin with two
 4important distinctions:
 5
 6 - Fewer dependencies
 7 - Python 3 compatible
 8
 9The system is used to allow multiple Python packages to provide plugins within
10a namespace package, where other packages will locate and utilize. The plugins
11themselves are modules in a namespace package where the namespace identifies
12the plugins in it for some particular purpose or intent.
13
14For example, if I was building a log parser, I might tell users that he parser
15will look for plugins in the `logfilter` namespace. Someone else could then
16provide a module named `logfilter.normalizedates` and my parser would find this
17plugin, load it, and use it to filter the log entries.
18
19It would be up to me to document what the plugin actually looks like, based on
20how I need to use it in my project.
21
22## Using plugins
23
24    from straight.plugin import load
25
26    class Skip(Exception):
27        pass
28
29    plugins = load('logfilter')
30
31    def filter_entry(log_entry):
32        for plugin in plugins:
33            try:
34                log_entry = plugin.filter(log_entry)
35            except Skip:
36                pass
37        return log_entry
38
39## Writing plugins
40
41    # logfilter/__init__.py
42    from pkgutil import extend_path
43    __path__ = extend_path(__path__, __name__)
44
45    
46    # logfilter/hide_extra.py
47
48    from logfilter import Skip
49
50    def filter(log_entry):
51        level = log_entry.split(':', 1)[0]
52        if level != 'EXTRA':
53            return log_entry
54        else:
55            raise Skip()
56
57## Module and Class Plugins
58
59straight.plugin is able to load both modules and classes, depending on your
60needs. When you call `load()` with a namespace, you'll get all the modules
61found under that namespace. When you call it with the optional `subclasses`
62parameter, all the classes which are subclases of the given type will be
63given.
64
65    # Example
66
67    from straight.plugins import load
68
69    plugins = load("ircclient", subclasses=IrcClientCommand)
70
71