[KSS-checkins] r47399 - in kukit/kss.base/trunk: . kss/base

[jvloothuis at codespeak.net]

Author: jvloothuis
Date: Thu Oct 11 20:49:03 2007
New Revision: 47399

Added:
   kukit/kss.base/trunk/kss/base/plugin.txt
Modified:
   kukit/kss.base/trunk/kss/base/plugin.py
   kukit/kss.base/trunk/kss/base/tests.py
   kukit/kss.base/trunk/setup.py
Log:

Added more tests for the plugin system

Changed identifiers used in setup.py


Modified: kukit/kss.base/trunk/kss/base/plugin.py
==============================================================================
--- kukit/kss.base/trunk/kss/base/plugin.py	(original)
+++ kukit/kss.base/trunk/kss/base/plugin.py	Thu Oct 11 20:49:03 2007
@@ -8,6 +8,11 @@
 class Plugin(object):
     priority = 100
 
+    javascripts = ()
+    extra_javascripts = ()
+    selectors = ()
+    commandsets = {}
+
     def register_commandsets(self, registry):
         for name, commandset in self.commandsets.iteritems():
             registry.register(name, commandset)
@@ -30,6 +35,12 @@
            return javascripts_from(os.path.dirname(os.path.abspath(path)))
     return javascripts
 
+def module_path(mod):
+    return os.path.join(os.path.dirname(os.path.abspath(mod.__file__)))
+
+def file_below_module(mod, subpath):
+    return os.path.join(module_path(mod), *subpath.split('/'))
+
 def load_plugins(*names):
     for name in names:
         for entry_point in iter_entry_points('kss.plugin', name):

Added: kukit/kss.base/trunk/kss/base/plugin.txt
==============================================================================
--- (empty file)
+++ kukit/kss.base/trunk/kss/base/plugin.txt	Thu Oct 11 20:49:03 2007
@@ -0,0 +1,79 @@
+=======
+Plugins
+=======
+
+KSS is a framework which is meant to be extended. An extension is a
+simple Python package with some setuptools glue.
+
+Before any plugin can be used it must be activated. There is a
+function for this which will be shown later. We will now just query
+all activated plugins and show that it is empty.
+
+  >>> from kss.base.plugin import activated_plugins
+  >>> tuple(activated_plugins())
+  ()
+
+We will now create a sample registration. A registration consists of a
+class like you can see below.
+
+The first thing we need to do is import the `Plugin` base class. This
+contains a few methods used in registration.
+
+  >>> from kss.base.plugin import Plugin, file_below_module
+
+Now we can create our class. We will reuse the core commands in this
+example.
+
+  >>> import kss.base
+  >>> from kss.base.corecommands import KSSCoreCommands
+  >>> from kss.base.coreselectors import CSS
+
+  >>> class ExamplePlugin(Plugin):
+  ...     javascripts = [file_below_module(kss.base,
+  ...                                      'javascript/plugin.js')]
+  ...     extra_javascripts = []
+  ...     commandsets = {
+  ...         'example': KSSCoreCommands,
+  ...         }
+  ...     selectors = [CSS]
+
+As you can see from the lines above the registration has a few things
+in it. The first thing is registering the Javascripts. All items in
+the list to the `javascripts` variable should be full paths to your
+plugins Javascript. This should not list any third party Javascript
+files. For this you can use `extra_javascripts`.
+
+The `commandset` var is a dictionary containing the mapping with
+identifiers and the command set factory. When using KSS you would
+normally use this identifier for the lookup of command sets.
+
+We can also register additional selectors. 
+
+Now that we have our registration it is time to hook it up with the
+setuptools registry.
+
+  >>> import pkg_resources
+
+  >>> class FakeEntryPoint(pkg_resources.EntryPoint):
+  ...     def load(self):
+  ...         return ExamplePlugin
+
+  >>> distribution = pkg_resources.Distribution(location='.')
+
+  >>> entry_point = FakeEntryPoint('testing', 'modname',
+  ...                              attrs=('somemethod',),
+  ...                              dist=distribution)
+
+  >>> distribution._ep_map = {'kss.plugin': {'kss-testing': entry_point}}
+
+  >>> pkg_resources.working_set.add(distribution)
+
+After this we can load our newly created plugin.
+
+  >>> kss.base.load_plugins('kss-testing')
+
+Now that we have activated our plugin it should show up as activated.
+
+  >>> tuple(activated_plugins())
+  (('kss-testing', <ExamplePlugin object at ...>),)
+

Modified: kukit/kss.base/trunk/kss/base/tests.py
==============================================================================
--- kukit/kss.base/trunk/kss/base/tests.py	(original)
+++ kukit/kss.base/trunk/kss/base/tests.py	Thu Oct 11 20:49:03 2007
@@ -5,7 +5,8 @@
     suite = unittest.TestSuite((
         doctest.DocFileSuite(
             'README.txt', 'selectors.txt',
-            'registry.txt', 'corecommands.txt',
+            'registry.txt', 'plugin.txt',
+            'commands.txt', 'corecommands.txt',
             package='kss.base',
             optionflags=doctest.ELLIPSIS|doctest.REPORT_ONLY_FIRST_FAILURE,
         ),

Modified: kukit/kss.base/trunk/setup.py
==============================================================================
--- kukit/kss.base/trunk/setup.py	(original)
+++ kukit/kss.base/trunk/setup.py	Thu Oct 11 20:49:03 2007
@@ -9,7 +9,13 @@
 """,
       # Get more strings from http://www.python.org/pypi?%3Aaction=list_classifiers
       classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Framework :: Paste",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: GNU General Public License (GPL)",
+        "Operating System :: OS Independent",
         "Programming Language :: Python",
+        "Programming Language :: JavaScript",
         "Topic :: Software Development :: Libraries :: Python Modules",
         ],
       keywords='',