[Grok-dev] On the Grok API

Luciano Ramalho ramalho at gmail.com
Thu Jun 7 16:28:34 EDT 2007


When I first started reading the source of apps made with Grok, I
found code like this a little strange:

#################

class WorkflowIndexes(grok.Indexes):
    grok.site(Blog)
    grok.context(IWorkflowState)
    grok.name('entry_catalog')

    workflow_state = index.Field(attribute='getState')
    workflow_id = index.Field(attribute='getId')

#################

What bothered me were those calls to grok functions right after the
class declaration. Those calls have a declarative intent, and perhaps
would be class annotations if Python's syntax allowed.

Then I remembered that in Ruby on Rails, they have similar declarative calls:

#################
class User < ActiveRecord::Base
    validates_presence_of :name
    validates_uniqueness_of :name
    attr_accessor :password_confirmation

    def self.authenticate(name, password)
        user = self.find_by_name(name)
        if user
            expected_password = encrypted_password(password, user.salt)
            if user.hashed_password != expected_password
                user = nil
            end
        end
        user
    end
    # (... more code would follow ...)
#################

As you can see, in Rails they use the wider syntatic variability of
Ruby to make the declarative statements look different from regular
function calls by omitting the parenthesis around the args in the
declarative calls, but using parenthesis in the usual function calls.

In order to make this distinction explicit in Grok, we could use a
different namespace for those declarative functions. For example, we
could have:

#################
from grok import declare

class WorkflowIndexes(grok.Indexes):
    declare.site(Blog)
    declare.context(IWorkflowState)
    declare.name('entry_catalog')

    workflow_state = index.Field(attribute='getState')
    workflow_id = index.Field(attribute='getId')
#################

Of course, instead of declare we could have another word. Some shorter
alternatives would be let or bind.

This whole idea is in keeping with a usability principle stated by
Donald Norman, that similar things should look similar, and different
things should look different.

I maybe too new to Grok to be making these kinds of suggestions, but
the whole issue just occurred to me because I am new, and I figure one
of my missions during this summer is to give you this perspective.

Cheers,

Luciano


More information about the Grok-dev mailing list