[Grok-dev] Naming of grok.provides
Philipp von Weitershausen
philipp at weitershausen.de
Tue Oct 14 04:02:53 EDT 2008
Kevin Teague wrote:
> On Oct 12, 2008, at 11:19 PM, Thomas Lotze wrote:
>> We recently noticed that the grok.provides directive is not well-
>> The documentation states that "if the local utility implements
>> more than one interface or if the implemented interface cannot be
>> determined, grok.provides() is required to disambiguate for what
>> interface the local utility will be registered."
>> OTOH, in zope.interface terminology, the term "provides" has a clear
>> meaning in contrast to "implements": if a class, for instance,
>> implements a certain interface, its instances are said to provide it.
>> We feel that something should be done about this contradiction of
>> terminologies as it confuses not only newcomers to Grok. Beyond a
>> documentation improvement, what would be an acceptable fix given that
>> this directive is rather close to Grok's core?
> Yeah, the text in the Grok Reference docs is even more confusing (and
> wrong ... although I think I wrote that.). I've just updated that text
> to read:
> :func:`grok.provides` -- disambiguate which interface is registered
> .. function:: grok.provides(interface)
> Explicitly specify with which interface a component will be
> looked up. If a class declares that it implements several
> :func:`grok.provides` can be used to disambiguate which interface
> will be
> registered with the Zope Component Architecture.
That's a pretty good definition. Thanks!
> But even with clearer documentation it's still somewhat confusing?
> Maybe grok.registers is clearer?
Or grok.register_for(). Consider this example::
> Since any class implements many
> interfaces that is used to create a component, that component is going
> to provide many interfaces - it's just used to state which interface
> is registered with the CA that it's interested in as providing for the
> CA among the many it provides.
Right. I think we chose the name grok.provides() initially because the
keyword parameter of the registrations functions in zope.component is
called "provides". That's a poor excuse, of course.
More information about the Grok-dev