Differences between revisions 2 and 9 (spanning 7 versions)

Example

This is a generalization of the technique used in setuptools so people can write plugins for commands.

Let's take an example: you have a command where you create a list of files to build a file list (a manifest).

You provide a default system to build this list but you know some people will probably provide other strategies to build that list.

So let's declare a user option, called "manifest-makers", where an ordered list of plugins name can be declared.

We also declare a new attribute called extensible_options, to declare the list of options that are used to extend the command.

class MyCmd(Command):

    user_options = [('manifest-makers', None,
                     'Plugins to build the manifest file')]

    extensible_options = ['manifest-makers']

    def initialize_options(self):
        # this is a regular user option
        self.manifest_makers = ['svn', 'template', 'hg']
        self.files = []

    def finalize_options(self):
        pass

    def run(self):
        # this will build the filelist by running the plugins
        self.run_extension('manifest-makers')

What happened ? In the initialize options, we declared default values for the manifest_makers attribute : three plugins called 'svn', 'template' and 'hg'.

The Command will load these plugins using setuptools entry point called: "distutils.MyCmd.manifest_makers". It will load them at the end of the option finalization.

Then, a new API called "run_extension" allows MyCmd to run these plugins.

Each plugin receives the command and the name of the option in argument and is free to work over the command and its distribution.

For example, the signature for the svn plugin is :

def svn(cmd, name):
    # work done here on the command

Read more about how to create plugins with entry points, and what they are, here : http://lucumr.pocoo.org/2006/7/30/setuptools-plugins

-  ⇤ ← Revision 2 as of 2009-04-19 11:40:21 → 
  Size: 2040
  Editor: tarek
  Comment:
+   ← Revision 9 as of 2009-04-20 14:37:52 → ⇥
  Size: 2234
  Editor: tarek
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 4:
-can write plugins to add files registered in special index files from 
various version control systems.
+can write plugins for commands.
-Line 7:
+Line 6:
-You have a command where you create a list of files to build a manifest.
+Let's take an example: you have a command where you create a list of 
files to build a file list (a manifest).
-Line 17:
+Line 16:
-We also declare a new attribute called `extensible_options`, 
like `boolean_options`, that points the user options that are used
to extend the command.
+We also declare a new attribute called `extensible_options`, to declare
the list of options that are used to extend the command.
-Line 27:
+Line 25:
-    extensible_options = ['manifest_makers']
+    extensible_options = ['manifest-makers']
-Line 39:
+Line 37:
-        self.run_extension('manifest_makers')
+        self.run_extension('manifest-makers')
-Line 46:
+Line 44:
-The Command will load these plugins using setuptools entry point called: "distutils.MyCmd.manifest_makers".
+The Command will load these plugins using setuptools entry point called: "distutils.!MyCmd.manifest_makers".
-Line 49:
+Line 47:
-Then, a new API called "run_extension" allows MyCmd to run these plugins.
+Then, a new API called "run_extension" allows !MyCmd to run these plugins.
-Line 51:
+Line 49:
-Each plugin received the command and the name of the option in argument and is free
to work over the command, the distribution and so forth.
+Each plugin receives the command and the name of the option in argument and is free
to work over the command and its distribution.

For example, the signature for the svn plugin is :
{{{
def svn(cmd, name):
    # work done here on the command
}}}

Read more about how to create plugins with entry points, and what they are, here : http://lucumr.pocoo.org/2006/7/30/setuptools-plugins

Page

User

Example

Implementation