[Grok-dev] Re: On the Grok API
faassen at startifact.com
Tue Jun 12 16:06:37 EDT 2007
Brandon Craig Rhodes wrote:
> Martijn Faassen <faassen at startifact.com> writes:
>> The problem with supporting this is that we do require another import:
>> import grok
>> from grok import declare
> The grok module itself cannot do "import grok.declare as declare"?
You'd have people write:
? It's a bit longer, and I'd prefer to do this for less common case.
Grok's interfaces.py is quite clear in distinguishing between the kinds
of things that can be imported, so it's instructive to study it:
IGrokBaseClasses - base classes that are grokked
IGrokErrors - errors that Grok can raise
IGrokDirectives - class or module-level directives
IGrokDecorators - grok's decorators ('subscribe' and 'action')
IGrokEvents - imports of the common Zope events
IGrokAPI - grok, url, notify, getSite, PageTemplate, PageTemplateFile,
Fields, AutoFields, action (hm, the latter appears a duplicate of our
I think base classes and directives belong in 'grok' definitely. They're
easily distinguished with upper case for classes, lower case for
directives. The problem is that non-directives are spelled the same as
directives. Let's see what else is there.
Errors are also easily distinguished, as they both end with 'Error'. The
same goes for event - they all have 'Event' at the end of the name. I
don't see these are problem cases.
Decorators are a bit harder to distinguish, though since we only have
two so far (actually three, as grok.require can double as a decorator
too), with adapter and implements coming soon, and they do have a
declarative function, I think this isn't too bad. You can get
potentially confused however and try to use a decorator as an directive
or vice versa. In case of grok.require this will even sometimes work..
Now IGrokAPI is the most obvious mismash and might confuse people as the
rest is all declarative.
Some of the stuff in there is actually still declarative, just in a
different way than what we saw before:
* PageTemplate, PageTemplateFile can be used to create instances that
will be grokked by InstanceGrokkers
* Fields, AutoFields are declarative on forms, but look different than
normal directives in that they set a value. I can imagine moving all
form support into a grok.formlib module eventually, and saying
grok.formlib.action and grok.formlib.Fields().
* grok, url, notify and getSite are a mix of things we need often in
typical applications, and are convenient to have nearby. I can imagine
moving these into something like grok.util eventually, and use them
using grok.util.getSite() and such.
With a bit more work we could make the rule "everything in the 'grok'
package is declarative" work. People might still be surprised initially
looking at Grok's directives, of course. Calling functions on a class
level is uncommon enough for them to stand out, especially if we explain
the 'grok' import only gets you declarative stuff.
More information about the Grok-dev