[Kss-devel] API proposal

[Martijn Faassen]

Balazs Ree wrote:
[snip]
> The way Jeroen implemented the commandsets in kss.base first,
> mainly considers the actual commandsets that are in the core, and
> simplify these cases. However we have more complex usage needs in zope
> and plone that the previous version supported. With the way the
> kss.base handles the commandsets, 
> - we cannot support our current needs with Zope and Plone, 
> - but we also don't want different type of commandsets in python, Zope, 
> and server X, 

I disagree with the second requirement. Why *do* you want the same type 
of commandset for all these servers? What's the point? I can't reuse the 
commandset that I write for a Zope app in server X anyway, right? Any 
resuable bits that do exist I can factor out into independent libraries.

I think that anything that relies on kss.base only should only have to 
deal with commandsets that are as close to straightforward Python 
possible, which means a module with functions in it. Or a module with an 
instance of a class in it (where the methods are the commands), if you 
need to be able to parameterize commandsets for some reason (in specific 
cases). The great advantage of this is that when people follow the 
import trail (something all Python programmers can do), they can find 
the implementation. Any registry-based approach breaks this.

Some commandsets may implement the same abstract interface. You can then 
look up the one relevant in your particular application. I'm somewhat 
skeptical of this requirement myself, as I've only heard the 'different 
effects libraries' examples so far, which doesn't convince me. How many 
of these protocols are there right now in the real world? Do they 
actually have multiple implementations?

Anyway, putting aside this skepticism, let's imagine we have an effects 
commandset and there's a reimplementation of this (the example I keep 
hearing about). I want to use this other implementation in my 
application. So I change the import. This is straightforward and 
something that Python programmers understand. It's not like I don't need 
to test my application with this new effects library anyway.

The word 'commandset' may be able to go away. Instead people can use the 
familiar concept of a "python module".

Now you could envisage a general framework that helps you get an 
implementation of a commandset interface dynamically, based on some 
configuration setting and pulling it from a registry. Zope 3 has such a 
story for registration (the component architecture). So when *I* need 
this, I'll use zope.component. kss.zope could offer some approach that 
uses this. Other systems have different stories for this, or will grow 
ad-hoc stories for this.

I want the Zope 3 story to look like the Zope 3 story, and the other 
frameworks will have to be on their own. Perhaps eventually something 
like kss.registry might grow if some of these frameworks want to reuse 
the same registry after they gain some experience with this and it turns 
out to be an important requirement. I doubt a Zope 3 application will 
want to use this, as one of Zope 3's strongest points is its powerful 
configuration story.

> 1. KSS plugins have no global import, is Good

This is not good in the lowest layer. The lowest layer should be simple 
to understand for a Python programmer. If you want this kind of stuff, 
please use the Zope 3 component architecture, which was born to do this 
kind of thing and is at least something you don't need to reinvent.

 > but in this case I
> am against loosing the import independance, and allow to decouple the 
> commandsets from the kss registry, thus loosing all advantage of 
> registration (like portability and platform independence).

If a developer wants import independence for a particular command set, 
please tell the developers to write a Python module that does this:

def get_right_module():
     if some_configuration():
          import foo
          return foo
     else:
          import bar
          return bar

and use 'get_right_module'.

An arbitrary Python developer will be able to come up with this 
themselves. I won't come up with this but will use the component 
architecture when I need this, and this offers more pluggability. Many 
python developers don't want to know about such things as they don't 
*need* it. Don't bother them with this. Point them to zope.component if 
they do need it, or let them invent their own approach. They do this anyway.

> I would like to add that (unlike Martijn said) the commandset's name
> is not "just a string". It is a fully dashed global identifier of the
> commandset (Example plone-issuePortalMessage, but we will support
> multilevel namespaces my-fancy-app-command any moment):

(I'm not sure why I am said to have said this)

Why invent your own namespace construct when Python already has one?

>  The slight separation from python land also
> helps to understand to the reader of the code that executes is a
> registered part of a kss plugin - much more important then to see
> which python module it's importing from.

I assume that if you import KSS commands from a module, you already know 
you're dealing with KSS here. Use a global 'kssplugin' namespace that 
peopple can use their KSS plugins under if you're concerned with this, 
just like Zope uses 'zope'. Don't enforce that (Zope doesn't).

[snip]
> We may think, however, other ways to make the syntax usage sweeter, if 
> the view.getCommandSet() is the biggest annoyance in the
> story. The view.getCommandSet can be removed and instead we can provide a 
> kss import namespace like

To me, it's not just the syntax. It's mostly the semantics. It that it's 
an unnecessary abstraction at this level, that hinders the ability of a 
Python programmer to find things. If you used modules, a developer can 
find a module and then have an immediate idea of how you can use it (you 
don't need to know how it's registered, you can import it). If you see a 
module in use, you can go and find the module as you know its dotted name.

[snip]
> 2. Zope commandsets do need to access the view

I'll rephrase this: a Zope specific command will need access to the Zope 
view.

You can pass in the view as a parameter, or you could implement your 
Zope-specific set of commands as a class that takes the view as the 
argument. That's up to the developer. I disagree with tying this to the 
kss.base discussion, as I don't agree with the basic requirement that 
requires this.

Commands are much like functions or methods. I think you shouldn't 
require people to have to make a choice between implementing their own 
commands as functions, or methods, in the core of your framework.

[snip]
> For example, the plone-issuePortalMessage command needs to access not
> only to commands, but also to the content and the request. This could
> not be handled sanely in the plain-python way, unless an arbitrary
> number of parameters were passed to the actual command implementations
> which would be insane. 

I probably don't understand something here, but why can't the *Zope 
specific commands* get these extra parameters, while the underlying core 
commands on top of which you're building them don't? Is this again a 
result of the requirement that commandsets look the same for all Python 
frameworks?

> However with the "commandset as adapter"
> pattern, this is easy since the implementation-dependent parameters
> are all hidden. (In addition every other system may also want to
> implement its own
> issuePortalMessage.)

If you want to use adapters, please use zope.component. I don't want to 
use a reimplementation of zope.component. I also don't think Python 
programmers in general are looking for this.

[snip]
> If the proposal in the thread becomes the supported way of API for 
> commandsets, first we loose import location independence, 

Location independence doesn't belong in the core. Python has location 
dependence, so there's no requirement to get rid of this dependence in a 
general Python library.

> then we also 
> won't be able to support existing commandsets code this way. 

That's only because of the requirement you want commands to look like 
each other in different frameworks, while still supporting the different 
requirements of each framework. You're essentially looking to abstract 
over different frameworks, and that's a very risky business. Commands 
already look like each other as they look like Python functions, and 
sets of commands are like modules or classes. The universal way to plug 
into any framework is by writing an actual library.

> As a result 
> all the code that cannot be supported and inevitably will be implemented 
> out of scope from kss (= differently from the supported way), which means 
> loosing the advantage of platform independence and portability.

Platform independence for Zope specific code dealing with Zope views, 
contexts and requests?

> At the same time I feel that the "commandset adaptation" pattern would 
> allow to keep best of all worlds, and it would not limit the
> implementations. It may not be the most perfect option either so it's
> essential to understand for me to get your reactions on the issue.

I think it is limiting implementations and makes KSS harder to 
understand for Python programmers. I myself am familiar with adaptation 
but I already am committed to the use of zope.component.

Regards,

Martijn