[Grok-dev] Re: proposal: grok.title() and grok.description()

[Martijn Faassen]

Hey,

Tres Seaver wrote:
[snip]
>> The arguments to both is a unicode string or a message id: human 
>> readable text.
> 
> Can we stay with the grokkish convention that ASCII strings are alllowed
> as well?  I *hate* the dead chicken of the leading 'u'.

Yes, of course. Whenever I say 'unicode string', just read "unicode 
strings and plain ascii strings". I pushed for that one in Grok. :) It 
will get us in trouble if we ever convert to Python 3.0, but that'll be 
only one of our troubles.

>> These directives should be usable on just about any class, ranging from 
>> Model to View to Permission.
>>
>> The idea is then that an application's user interface can access this 
>> data (this means we need to come up with a good API to access this kind 
>> of grok-defined attribute in the grok module. Anyone have any ideas?). 
> 
> How about assigning '__doc__' on the object ;)?  Actually, one might
> hack the directives so that they *returned* the values when passed a
> non-basestring / message ID object.

Isn't __doc__ used by docstrings? Not sure whether you're not kidding 
(there's a smiley) but just to make it clear: docstrings tend towards 
programmer-readable text and this is for UI text. Currently the admin UI 
uses the docstring to present some information about an application, but 
I'd rather have it use title and description. (then again, applications 
are somewhat special, as typically you'd only want to see the title of 
an application in a UI that *manages* applications such as the admin UI).

Hacking the directives to return the equivalent value when passed 
something is an interesting idea. Generalizing this seems difficult 
however, as grok.context() already can take class arguments.

[snip]
>> We need sensible defaults for these two attributes. grok.description() 
>> should default to grok.title().
> 
> I'd rather see it default to empty.

Somewhat dangerous for the same reasons as spelled out below for 
grok.title()... Then again, perhaps not as much of a problem as for 
title, and that way you'd not see duplicated text. One wouldn't expect 
to see the description very often without showing the title as well, 
after all. So I think defaulting to the empty string is a better idea, 
indeed.

>> What about grok.title()? I think it 
>> would be bad if grok.title() defaulted to the empty string, as these 
>> don't show up in the user interface and give no clue as to what object 
>> you're dealing with. I therefore propose grok.title() should default to 
>> the class name. This gives a good hint on what's going on in a user 
>> interface where someone hasn't spelled out grok.title() yet for a 
>> particular class, which can then be easily fixed.
> 
> Defaulting to '__name__' is probably fine.  Another option is to do the
> "first line, rest" splitting of '__doc__'.
> 
>> What do people think?
> 
> +1 overall.

Thanks for the feedback! To summarize, two modifications to the proposal 
as prompted by your remarks:

* plain ascii text is allowed too.

* grok.description() should default to the empty string.

Regards,

Martijn