Better access to APIs in paths (was Re: [Zope3-dev] needing views clues - template/title troubles)

[Jeffrey P Shell]

On Sunday, February 23, 2003, at 07:23  AM, Jim Fulton wrote:
[SNIP]
> Zope 2 would make this really easy:
>
>   ob.title
>
> but to do that, Zope 2 requires that everyone include title
> in the content schema, which is bad. Worse, if someone forgets
> to define a title, then Zope 2 will acquire the title from some
> other object, which could be very suprising.

Worse yet, title *and* id could be an attribute, or a method.  I think 
that's why we included 'getId()' as the preferred way of getting the id 
(at least, that's what I always use, as there are no alarms and no 
surprises).  And as for title, in Zope 2 I often go "title_or_id()" 
because, again, it's more predictable as far as behavior goes.  So in 
this particular case, esp. in regards to title, Zope 2 doesn't actually 
seem to have an agreed upon API.  :/

> The thing Zope 2 does well here is to make common APIs convenient.
> The thing Zope 3 does well here is to be explicit.
>
> Maybe we can get the best of both. Suppose we define a new type of
> components called an "API" that is meant to be conveneint and informal.
> APIs would be registered for interfaces, like adapters, but would be
> looked up by name. There would be an "api" function, somewhat in the
> spirit of Python's super. Suppose we define an API attribute, title.
> We might register a title attribute hendler based on the zope dublin
> core something like this::
>
>    <api
>      name="title"
>      for="zope.app.interfaces.annotation.IAnnotatable"
>      factory="zope.app.dublincore.annotatableadapter.TitleAPI"
>      >
>        title meta-data attribute
>
>        The title API attribute provides access to the (unqualified)
>        Dublin-Core "Title" meta-data element.
>    </api.
>
> Then from Python, we could do:
>
>   api(ob).title
>
> More importantly, we invent a path syntax for ZPT that would
> let us get at APIs easily. The question is, how to spell this. You 
> want,
> in a path expression, to indicate an API that is not really an 
> attribute
> of an object.  The thing you want is in a different namespace.
>
> Zope 3 has a notion of namespace control in path expressions.
> (This is similar to the namespace control facilities in XPATH, FWIW.)
> In a path, you can prefix a name with a namespace prefix of the form
> "++namespace++". So, for example, to access a view named "foo" you
> could use:
>
>   context/++view++foo

Ergh..  So those ++'s are going to be fairly common?  I remember the 
early discussions about these things, and I know that they're 
necessary.  At the same time..  yuck.  I keep seeing them and going "I 
hope I don't have to type those things alot", hoping that they're just 
application level things that are always generated by something in the 
machinery, like cookie information being grafted into a URL, and never 
something I'd have to do by hand.  My main concern was about 
referencing modules/packages/whatever passes for Python Script 
Replacement and having to go through a bunch of ++hoops++ in a page 
template; contrasting 'modules/ZTUtils' or 
'modules/Products/MyStuff/helpful_utils' to 
'something/++etc++fribnoids/MyStuff/helpful_utils', the last option is 
something I hope can be avoided.

> Accessing views is *so* common, we have a short-hand, @@:
>
>   context/@@foo

I guess these are generally going to be generated by hand as well?  
Ergh.  Guess so.  Path syntax is useful enough that I doubt I'll be 
bothered too much.

> We could provide an api namespace:
>
>   context/++api++title

Can 'context/++api++' be bound in pagetemplates?  Like:

<tal:setup define="global api global/++api++" />

then later:

<h1 tal:content="api/title">foo</h1>

Typing in all those pluses could get tiresome.  At the same time, 
coming up with too many shortcuts could take back into murky waters 
('@@' is nice, but I'm afraid too many more different notations could 
turn path expressions into perlish expressions, requiring the user in 
this scenario to have to remember the difference between '@@' and '++' 
and anything else we come up with; not to mention the dynamic path 
expansion stuff (context/?foo/blat) that I've grown quite fond of in 
current ZPT).

> which isn't bad at all, but it might be nice to have an even shorter 
> version,
> like:
>
>   context//title
>
> or
>
>   context/++/title
>
> Thoughts?

This seems to be the area where "explicit is better than implicit" gets 
yucky.  I've been looking at the ++ and @@ signs in fear already, and I 
hope that other Zope 2 migrators don't flinch too strongly when they 
come across them.  I know that they're necessary and I sure don't have 
any better suggestions right off the bat.

Well, the only suggestion I have is to put callable-looking modifiers 
on to dynamic path expression:

context/?api{dc/created}
or context/$api{dc/created}
or context/@@api{dc/title}

I don't know why those look better to me though.  I may just be more 
familiar with them after doing all the ZPT work I've done, whereas the 
++foo++ things still cause my brain to derail for a second whenever I 
come across them.

> Final note: The audience of "APIs" is scripters, so there should be an
>             emphasis on informality and convenience. In the example, 
> above,
>             we defined an API attribute. APIs coould be functions or 
> even
>             complex objects. For example, we could provide a Dublin 
> Core
>             API that provided full access to dublin core data, as in:
>
>               context/++api++dc/created