[Grok-dev] on the name "Grok"

[Martijn Faassen]

Hi there,

Since Lennart and Godefroid had such success with Grok in Zope 2, and 
naming issues came up once again, I thought I'd sketch my idea on a 
policy for the name 'Grok', and the package name 'grok'.

With just Grok, it's simple:

* you import from grok

* grokked components such as grok.View are in the grok namespace

* grok directives are in the grok namespace too

Then we had grokcore.component. This is a strict subset of Grok, that 
Grok will be using itself, intended to be reusable outside of Grok:

* you do: import grokcore.component as grok

* everything (both components and directives) works as a strict subset 
of grok; you have adapters and such

* grok imports these things into its own namespace.

I think this usage is all right, as grokcore.component is considered to 
be a strict subset of Grok. Using the name 'grok' here will lead to 
relatively little confusion, and it *is* much prettier to use 
'grok.context()' instead of 'grokcore.component.context()'.

Now we have five.grok. This is a partial re-implementation of Grok. It 
is a workalike to Grok in Zope 2:

* you do: from five import grok

* everything either works as Grok in a Zope 2 context, or not if 
grok.five doesn't have that support yet.

* it reuses grokcore.component and imports this into its own namespace.

I also think this naming is all right, as five.grok tries to be an 
implementation of the same module interface as Grok itself offers. It's 
a port of Grok to Zope 2.

There is also 'plone.grok'. This provides plone-specific components and 
grokkers, dealing with Plone specific concepts such as portlets. In 
order to use it, you import from it. I think this name is very *wrong*. 
It leads people to believe that these base classes exist in Grok, which 
they do not. It's not implementing standard Grok concepts at all, but 
extends Grok. It therefore the namespace shouldn't have 'grok' in it. 
Ideally it's just something that is folded into existing Plone packages.

I think using a new namespace looks fine for base classes. It may look a 
bit ugly if you introduce new directives. Hopefully we can avoid these 
most of the time, reusing standard grok directives. If a new directive 
does need to be introduced, it *should* be in the same namespace as the 
base class, unless we can somehow generalize it to Grok itself.

Absolutely out of the question is making the grok namespace 'magic', 
where you can plug in your own things, just so things read smoothly. 
Grok code is Python code. If see 'grok.foo', you should be able to go 
look at Grok's __init__.py, follow the chain of imports, and find the 
implementation. Importing it from other places is fine and standard 
Python. But we don't want to use registries here, as this is a kind of 
monkey-patching.

The general rules:

* ports to different platforms can be called 'grok'

* strict subsets of Grok should be called 'grokcore.<name>'. When using 
them, the user can use the word 'grok', in something like 'import 
grokcore.component as grok'. That said, this only works if you use only 
a single subset at the time.

* things that introduce new base classes or directives shouldn't be 
called 'grok'

* imports should behave like normal python imports; no magic registry 
behavior here.

Regards,

Martijn