[KSS-checkins] r51977 - in kukit/kss.base/trunk: docs src/kss/base
gotcha at codespeak.net
gotcha at codespeak.net
Sat Mar 1 10:57:26 CET 2008
Author: gotcha
Date: Sat Mar 1 10:57:19 2008
New Revision: 51977
Added:
kukit/kss.base/trunk/docs/HISTORY.txt
Modified:
kukit/kss.base/trunk/src/kss/base/__init__.py
kukit/kss.base/trunk/src/kss/base/javascript.py
kukit/kss.base/trunk/src/kss/base/javascript.txt
kukit/kss.base/trunk/src/kss/base/plugin.py
kukit/kss.base/trunk/src/kss/base/plugin.txt
Log:
- renamed `load_plugins`, `unload_plugins`, and `activated_plugins`
to respectively `activate`, `deactivate`, and `active_plugins`
- hopefully better wording for plugin.txt
Added: kukit/kss.base/trunk/docs/HISTORY.txt
==============================================================================
--- (empty file)
+++ kukit/kss.base/trunk/docs/HISTORY.txt Sat Mar 1 10:57:19 2008
@@ -0,0 +1,11 @@
+Changelog for kss.base
+
+ (name of developer listed in brackets)
+
+kss.base - 0.4dev Unreleased
+
+ - renamed `load_plugins`, `unload_plugins`, and `activated_plugins`
+ to respectively `activate`, `deactivate`, and `active_plugins`
+ [gotcha]
+
+kss.base - 0.3 Released 2008-02-12
Modified: kukit/kss.base/trunk/src/kss/base/__init__.py
==============================================================================
--- kukit/kss.base/trunk/src/kss/base/__init__.py (original)
+++ kukit/kss.base/trunk/src/kss/base/__init__.py Sat Mar 1 10:57:19 2008
@@ -1,4 +1,4 @@
from kss.base.commands import KSSCommands
from kss.base.selectors import selectors
-from kss.base.plugin import load_plugins
+from kss.base.plugin import activate
from kss.base.commands import xmldata, htmldata, cdatadata
Modified: kukit/kss.base/trunk/src/kss/base/javascript.py
==============================================================================
--- kukit/kss.base/trunk/src/kss/base/javascript.py (original)
+++ kukit/kss.base/trunk/src/kss/base/javascript.py Sat Mar 1 10:57:19 2008
@@ -1,13 +1,13 @@
import os
-from kss.base.plugin import activated_plugins
+from kss.base.plugin import active_plugins
from kss.base.compression.javascript import compress
def concatenated(include_extras=False):
'''Concatinate the Javascript files for all activate plugins'''
scripts = []
- for id, plugin in sorted(activated_plugins(),
+ for id, plugin in sorted(active_plugins(),
key=lambda item: item[1].priority):
if include_extras:
javascripts = plugin.javascripts + plugin.extra_javascripts
@@ -24,11 +24,11 @@
return compress(concatenated(include_extras), compression_level)
def extra_scripts():
- '''Return a dictionary of the extra javascripts for all activated
+ '''Return a dictionary of the extra javascripts for all active
plugins'''
scripts = {}
- for id, plugin in activated_plugins():
+ for id, plugin in active_plugins():
for filename in plugin.extra_javascripts:
f = open(filename, 'r')
scripts[os.path.basename(filename)] = f.read()
Modified: kukit/kss.base/trunk/src/kss/base/javascript.txt
==============================================================================
--- kukit/kss.base/trunk/src/kss/base/javascript.txt (original)
+++ kukit/kss.base/trunk/src/kss/base/javascript.txt Sat Mar 1 10:57:19 2008
@@ -22,8 +22,8 @@
Now if we run the code again after we activate a plugin we get
something more interesting.
- >>> from kss.base import load_plugins
- >>> load_plugins('kss-core')
+ >>> from kss.base import activate
+ >>> activate('kss-core')
>>> concatenated()
'/*\n* Copyright (c) 2005-2007\n* Authors: KSS Project Contributors...'
@@ -42,8 +42,8 @@
Finally we will unregister the core plugin to clean up.
- >>> from kss.base.plugin import unload_plugins
- >>> unload_plugins('kss-core')
+ >>> from kss.base.plugin import deactivate
+ >>> deactivate('kss-core')
Packed
@@ -63,7 +63,7 @@
So now we activate a plugin.
- >>> load_plugins('kss-core')
+ >>> activate('kss-core')
By default the packed function does no packing.
@@ -84,8 +84,8 @@
We will again unregister the core plugin to clean up.
- >>> from kss.base.plugin import unload_plugins
- >>> unload_plugins('kss-core')
+ >>> from kss.base.plugin import deactivate
+ >>> deactivate('kss-core')
Extra scripts
@@ -104,7 +104,7 @@
If we activate a plugin we get something more interesting.
- >>> load_plugins('kss-core')
+ >>> activate('kss-core')
>>> extra_scripts()
{...'base2...js': ...}
@@ -113,5 +113,5 @@
Now we can cleanup the registry again.
- >>> from kss.base.plugin import unload_plugins
- >>> unload_plugins('kss-core')
+ >>> from kss.base.plugin import deactivate
+ >>> deactivate('kss-core')
Modified: kukit/kss.base/trunk/src/kss/base/plugin.py
==============================================================================
--- kukit/kss.base/trunk/src/kss/base/plugin.py (original)
+++ kukit/kss.base/trunk/src/kss/base/plugin.py Sat Mar 1 10:57:19 2008
@@ -24,11 +24,7 @@
def _selectors(self):
for name, selectors in self.selectors.iteritems():
for selector in selectors:
- if name is None:
- selector_id = selector.__name__
- else:
- selector_id = name + '-' + selector.__name__
- yield selector_id, selector
+ yield selector.type, selector
def register_selectors(self):
for id, selector in self._selectors():
@@ -67,7 +63,7 @@
return sorted(plugins,
key=lambda item: item[1].priority)
-def load_plugins(*names):
+def activate(*names):
def load(name):
for entry_point in iter_entry_points('kss.plugin', name):
plugin_factory = entry_point.load()
@@ -83,7 +79,7 @@
for name in names:
load(name)
-def unload_plugins(*names):
+def deactivate(*names):
for name in names:
for entry_point in iter_entry_points('kss.plugin', name):
plugin_factory = entry_point.load()
@@ -96,6 +92,6 @@
plugin_registry.unregister(name)
-def activated_plugins():
+def active_plugins():
return plugin_registry.items()
Modified: kukit/kss.base/trunk/src/kss/base/plugin.txt
==============================================================================
--- kukit/kss.base/trunk/src/kss/base/plugin.txt (original)
+++ kukit/kss.base/trunk/src/kss/base/plugin.txt Sat Mar 1 10:57:19 2008
@@ -2,33 +2,34 @@
Plugins
=======
-KSS is a framework which is meant to be extended. An extension is a
+KSS is a framework which is meant to be extended. A plugin 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.
+Before any plugin can be used, it must be active. There is a
+function to activate plugins that we will show later.
- >>> from kss.base.plugin import activated_plugins
- >>> tuple(activated_plugins())
+At startup, when we query for active plugins, we get an empty tuple.
+
+ >>> from kss.base.plugin import active_plugins
+ >>> tuple(active_plugins())
()
-We will now create a sample registration. A registration consists of a
-class like you can see below.
+We create a sample registration. A registration consists of a
+class as 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.
+The first thing we need to do is to import the `Plugin` base class. It
+holds a few items used by the 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.
+Now, we can create our class. (We reuse the core commands in this
+example.)
>>> import kss.base
>>> from kss.base.corecommands import KSSCoreCommands
>>> from kss.base.selectors import Selector
- >>> class silly(Selector):
+ >>> class Silly(Selector):
... type = 'example-silly'
... def __init__(self, value):
... self.value = value
@@ -41,28 +42,28 @@
... commandsets = {
... 'example': KSSCoreCommands,
... }
- ... selectors = {'example': [silly]}
+ ... selectors = {'example': [Silly]}
+
+The registration has a few items.
-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 first item is the list of the names of the Javascripts files that makes
+the client-side plugin. All names should be full paths.
-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.
+This list should not include any third party Javascript files.
+Those are declared in `extra_javascripts`.
-If we try the activate our plugin now it will not work.
+The `commandset` var is a dictionary that containins the mapping between
+command set factories and their identifiers.
+Those identifiers are used to look the command sets up.
- >>> kss.base.load_plugins('kss-testing')
+Before being able to activate our plugin, we need to hook its registration with
+`setuptools`.
+
+ >>> kss.base.activate('kss-testing')
Traceback (most recent call last):
...
KeyError: 'Plugin is not registered: kss-testing'
-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):
@@ -78,17 +79,14 @@
>>> distribution._ep_map = {'kss.plugin': {'kss-testing': entry_point}}
>>> pkg_resources.working_set.add(distribution)
+
+Let us activate our plugin.
-After this we can load our newly created plugin.
+ >>> kss.base.activate('kss-testing')
- >>> kss.base.load_plugins('kss-testing')
-
-Now that we have activated our plugin it should show up as activated.
-
- >>> tuple(activated_plugins())
+ >>> tuple(active_plugins())
(('kss-testing', <ExamplePlugin object at ...>),)
-
The additional selector we registered is now available in the selector
registry. It can be looked up based on the class name with the key
from the registrion as the namespace.
@@ -97,38 +95,37 @@
>>> print selectors['example-silly']('testing')
example-silly('testing')
-Finally we will unregister our plugin to clean up.
+Finally we deactivate our plugin to clean up.
- >>> from kss.base.plugin import unload_plugins
- >>> unload_plugins('kss-testing')
+ >>> from kss.base.plugin import deactivate
+ >>> deactivate('kss-testing')
-----------------
Utility functions
-----------------
-When you write a plugin you will need to do a few things. For some of
-these things there are helper functions available.
+When you write a plugin, you need to do a few things. We have defined
+helper functions.
Getting full path names for Javascripts
---------------------------------------
-One of the helpers which is usefull mostly for extra Javascripts is
-`javascripts_from`. This function whill recursively generate an
-iterator of all javascripts from a certain path.
+`javascripts_from` is usefull mainly for extra Javascripts.
+This function generates a recursive iterator of all javascripts
+starting from a given path.
>>> from kss.base.plugin import javascripts_from, module_path
>>> scripts = javascripts_from(module_path(kss.base))
-To test the output we will first sort the scripts (otherwise the test
+To test the output, we need to sort the scripts (otherwise the test
may fail on different systems). Keep this in mind when creating your
-own plugins. If you need a consistent order either sort the output or
-use a different way of creating the list of scripts.
+own plugins. If you need a consistent order, either sort the output or
+use a different way of computing the list of scripts.
>>> list(sorted(scripts))
[.../kukit/kukit/dom.js', ..., .../kukit/kukit/serveraction.js', ...]
-When we try to load from something which is not a directory we will
-get an error.
+If we try to load from an identifier which is not a directory, we get an error.
>>> import os
>>> javascripts_from(os.path.join(module_path(kss.base),
@@ -148,13 +145,13 @@
>>> from kss.base.plugin import available_plugins
Because we ship with the core plugin it should show up when we call
-it. Also the example plugin we make will show here.
+it. The example plugin we have made also shows up here.
>>> list(available_plugins())
[('kss-core', <kss.base.config.KSSCore ...), ('testing', <ExamplePlugin ...)]
-The sequence of this is based on the plugin priority. If we change the
-priority of the example plugin it will be the first one.
+The sequence of this is based on the plugin priority. We can change the
+priority of the example plugin to make it the first one.
>>> ExamplePlugin.priority = -99999
>>> list(available_plugins())
More information about the Kukit-checkins
mailing list