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

Mon Jul 10 10:49:43 CDT 2006

Hi Lloyd,

On Mon, 10 Jul 2006 10:25:35 -0500, <lloyd at paisite.com> wrote:

[snip]

> And Manlio Perillo and L. Daniel Burr have suggested that this series
> should focus on building an application -- pastepot or CRUD (Don't know
> myself what either of those are). This warrants further discussion. For  
> my
> part, I like the idea, but have the following reservations:
>

CRUD is just an acronym for Create, Read, Update, Delete, and so-called
"CRUD apps" have become a popular litmus test for how handy/useful a
web application framework is.  The typical CRUD application is used as
an example of how to use a framework to talk to an RDBMS, render data
as HTML, edit data, delete it, etc.  This sort of tutorial is popular
because a large number of web applications boil down to providing a
web UI for editing some data that lives in a database, hence my suggestion.

> -- I'd like to keep the adventures as generic as possible across many
> potential applications; I fear that focusing on one application may limit
> our scope.
>

See above.  CRUD is pretty generic.

> -- Different folks may have widely different levels of interest in
> different applications, whereas we all need to master the basics.
>
> -- Developing a production-ready application may get us into a bunch of
> nitty-gritty stuff that doesn't have much to do with Twisted, but does
> have a lot to do with good programming practice.
>

My suspicion is that the people looking for tutorials and quick-start type
of documentation are, in fact, trying to build a production application in
a big hurry, and want to find something to build on.  With that in mind, I
think that working up to a simple, but production-ready application would
meet with a great deal of approval.

> That said, maybe after we've covered the basics, using the example of a
> good application to put it all together may be an excellent idea. I don't
> think we're talking either/or here.
>

Agreed.

[snip]

> PS Here's the last code example from Techno Turkey's Adventures:
>
> Matt Goodall's Barebones Dynamic Web Server
>
> from twisted.application import internet, service
> from twisted.web import resource, server
>
> LOGPATH = './logs/access.log'
> PORT = 8080
>
> class DynamicResource(resource.Resource):
>     """A simple, dynamic resource with a name.
>     """
>
>     def __init__(self, name):
>         resource.Resource.__init__(self)
>         self.name = name
>
>     def getChild(self, name, request):
>         # if the child's name is '' - the empty segment - then return
>         # myself.
>         if name == '':
>             return self
>         # Return an instance of my type with the requested segment name.
>         return DynamicResource(name)
>
>     def render(self, request):
>         return '<html><p>I am a Dynamic Resource. My name is
> %r.</p></html>' % (self.name)
>
> application = service.Application('web-server')
> site = server.Site(DynamicResource('root'), logPath=LOGPATH)
> internet.TCPServer(PORT, site).setServiceParent(application)
>

The only thing I don't like about this example is that DynamicResource
is returning an instance of itself for requests to childrend of itself.

Granted, this is perfectly legitimate, but I think it introduces some
potential confusion for a new reader.  I would suggest just creating
a "ChildResource" (the nevow examples directory does this), and
perhaps returning that instead, to make it more clear what is being
done in getChild.

Thanks for everyone's efforts and feedback on this, I think we are
headed in the right direction now, and perhaps we will attain the
critical mass of contributions needed to make this documentation effort
a success.

L. Daniel Burr