[Kss-devel] API proposal

[Jeroen Vloothuis]

At the Grokkerdam sprint Godefroid, Martijn Faassen and I had a 
discussion about the current KSS API. The example below shows how we 
currently use it (in `kss.core`):

class SomeKSSView(KSSView):
    def update_something(self):
        core = self.getCommandSet('core')
        core.replaceInnerHTML('#some-node', 'some content')
        return self.render()

Behind the scenes this uses a named adapter lookup to get a command set. 
Martijn does not like this since it is not clear where the code is 
implemented (because of the lookup based on a string). To make this 
better Martijn and I came to this proposal:

from kss.base import core

class SomeKSSView(KSSView):
    def update_something(self):
        core.replaceInnerHTML(self.commands, '#some-node', 'some content')
        return self.render()

This makes it explicit where the code is implemented (see the import). 
Advantages of this proposal are that it would both work with a pure 
Python implementation (for kss.base) and makes the system a bit simpler 
(conceptually). The `core` name would be implemented in `kss.base` as a 
module where `replaceInnerHTML` is a function, something like this:

def replaceInnerHTML(commands, selector, value):
    """Replace the contents of a node (selector) with the new `value`"""
        commands.add('replaceInnerHTML', selector, html=htmldata(value))


This change will only affect the clients of `kss.base`.