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

Tue Jul 11 15:37:17 CDT 2006

On Tue, 11 Jul 2006 14:10:58 -0500, <lloyd at paisite.com> wrote:

[snip]

> Re: IRequest code:
>

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

>> 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