[Twisted-web] Re: Thoughts on documentation, wading into Twisted, Nevow, etc.

lloyd at paisite.com lloyd at paisite.com
Tue Jul 11 17:35:05 CDT 2006


Hi Daniel,

On Tue, July 11, 2006 4:37 pm, L. Daniel Burr wrote:

> I've got some suggestion for this IResource example, which I will
> detail below.

Valentino is better qualified to respond than I. But you've convinced
me... provided that we have a really good definition of "Resource."

"Resource" is one of the concepts that baffled me last year. I couldn't
get my head around what folks were talking about. Your phrase "The thing
that a URL.points to..." definitely helps me see the bigger picture.
Saying this, I realize that my own work has been moving away from the
simple "set of linked pages" model. The Resource concept should give me
better language to talk about what I've been doing.

Since naive folks like me are accustomed to thinking in terms of "pages,"
it would probably be good to sharpen up and present your argument that
many web apps today have more complex structures than "set of linked
pages." We could explicitly point out that  abstracting the notion of
"page" to "Resource," opens the mind to more creative possiblies, then
present a few examples of these possibilties. We should definitely include
"page" as an an example of a "Resource," along with a few other examples.

Want to try your hand at a crisp, evocative definition with examples?

Many thanks,

Lloyd

>
>>> from zope.interface import implements
>>>
>>> from nevow import inevow
>>>
>>> ##
>>> ## How does a request come to the Page?
>>>
>
> I'd really prefer to be talking about Resources right from the very
> start, rather than web pages.  Note that I mean Resource as in: "The thing
> that a URL points to".  Web applications are becoming a bit less
> page-centric these days, so it might be helpful to start the reader off
> with the Resource concept, rather than talking about pages.
>
>>> ##
>>> ## or How to use Nevow without all the fancy automations
>>> ##
>>>
>>>
>>>
>>> # This is a simple Root page object, the inevow.IResource interface
>>>
>
> Maybe something like this:
>
>
> "This is a simple resource, representing the root, or top-most resource
> of this site.  The inevow.IResource interface..."
>
>>> # tells us that it must implement 2 methods:
>>> # locateChild and renderHTTP.
>>> # locateChild is used to find children of the current page, it must
>>> return a # tuple of (page, remaining_segments) # if there is no page,
>>> and you want to display a 404 page, you will need to return # a None,
>>> () tuple.
>>>
>
> Let's make this simpler: nevow.rend.NotFound is a much more convenient
> and readable way to spell "None, ()".  So, I'd suggest we change this to
> something like the following:
>
> "locateChild is used to find children of the current resource.  It must
> return a tuple of (resource, remaining_segments).  If no child resource
> exists at this location, you may return nevow.rend.NotFound."
>
> This ignores the fact that you could also return your own custom error
> resource, but maybe that should be saved for later docs?
>
>>> class Root(object): implements(inevow.IResource)
>>>
>>> def locateChild(self, ctx, segments): # This locateChild is 'stupid'
>>> since it can only work if the tree of # pages is static. Anyway it
>>> will work for
>
> "if the tree of resources is static"
>
>
>>> our simple example if segments[0] == '': # If the server is looking
>>> for the root page segments will be ('',) # then renderHTTP will be
>>> called on self return self, () elif segments[0] == 'foo': # Now we
>>> received a request
>> whose
>>> segments had in the first position # the string foo # like
>>> http://example.org/foo/baz/ -> ('foo', 'baz')
>>> # after the page has been located we return it with the remaining
>>> segments # ('baz')
>>> return self.foo, segments[1:] else: return None, ()
> return
>>>
>>> def renderHTTP(self, ctx): # When the server needs to return a
>>> response to the request it will call # the renderHTTP method that will
>>> return a string of what needs to be sent. return """<html><body>Hello
>>> world!<br /> <a href="./foo" id="foo">foo</a></body></html> """
>>>
>>>
>>> class Foo(object): implements(inevow.IResource)
>>>
>>> def locateChild(self, ctx, segments): # segments is the remaining
>>> segments returned by the root locateChild # see segments[1:] if
>>> segments[0] == 'baz': return self.baz, segments[1:] else: return None,
>>> ()
>>>
>>>
>
> "return rend.NotFound"
>
>
> In general, I think it is better to replace the word "page" with
> "resource"
> so that we don't lock readers into thinking of everything as a page; so
> much of what make twisted and nevow handy comes into play when you stop
> thinking about web pages as the unit of work, and think about resources.
>
> Anyone agree, violently disagree?
>
>
> L. Daniel Burr
>
>
> _______________________________________________
> Twisted-web mailing list
> Twisted-web at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-web
>
>
>





More information about the Twisted-web mailing list