[Grok-dev] Re: On the Grok API

[Martijn Faassen]

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:

grok.declare.context()

? 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 
decorators)

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.

Regards,

Martijn