[Grok-dev] on the name "Grok"
faassen at startifact.com
Mon Apr 28 08:59:47 EDT 2008
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
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
* imports should behave like normal python imports; no magic registry
More information about the Grok-dev