[Twisted-web] documentation -- Techno Turkey's fifth adventure

[L. Daniel Burr]

Hi Lloyd,


On Sat, 15 Jul 2006 14:40:24 -0500, <lloyd at paisite.com> wrote:

[snip]

> So here's... Techno Turkey
>
>
> Dialtone's Resource Magic
>
>
> "It's magic!" said Techno Turkey.
>
> "What's magic?" asked Twisted Wizard Daniel.
>
> "I just type it in at the top of my browser and... shazamm... back comes
> just the page I'm looking for -- could be from anywhere in the world.  
> It's
> like casting a magic spell."
>
> "It's far more magical than you think," says Twisted Wizard Daniel. "Just
> consider it's name: 'Uniform Resource Identifier' -- URI."
>
> "I thought it was a URL," said Turkey.
>
> "That was before people understood it's full mojo. Back then they called
> it a 'Uniform Resource Locator.' But then they realized that it could be
> used to identify anything in cyberspace."
>
> "Anything?" asked Turkey.
>
> "Sure, anything. We use URI's to identify servers, webpages, web  
> services,
> images, sound files..."
>
> "But the only thing I ever get back are webpages."
>
> "That's because that's what static HTTP webservers do. They listen for
> their designated URI and return the specified HTML web page. But aided by
> the right software, they can return anything of a digital nature."
>
> Twisted Wizard Dialtone happened to be listening in.
>
> "Hey, Turkey old bird," said Daniel, "Want to see my Resource magic?"
>

Looks like a typo, above.  I think it is intended to read "said Dialtone".

[snip initial download/install stuff]

> Once downloaded:
>
> -- how to find Twisted and Nevow source directories

I'd just make sure twisted and nevow are installed in site-packages, though
other options are certainly possible.  In the spirit of not distracting the
reader from non-essential information, let's just pick one.

> -- how to set up development environment

Well, we've got to at least cover setup for Win32 and Linux.  I'd argue  
that
OS X and one of the BSDs deserves a little attention too.

> -- how to set up working directories -- user source, logs,

See my response to dialtone's recent email on this list, for my suggestion
regarding directory layout.

> -- how to set up path variables

I suggest using .pth files rather than path variables.  Using .pth files
should "just work" regardless of your OS, and not require any fiddling
around with the environment by hand.

So, basically, for a new web project, you'd create your project dirs, and
then stick a "myproject.pth" file in the site-packages directory,  
containing
"/path/to/my/project/topmost/folder"

> -- how to test development environment
>

To test that the dev environment is set up correctly, I'd just start up a
python interpreter prompt and import twisted, then import nevow, and  
lastly,
import myprojectpackage.

> Should be sufficiently detailed that even the slowest turkey on the farm
> can implement.
>
> Anybody up for fleshing in details for this page? I can edit, put it up  
> on
> the Turkey server, and link it into Turkey adventures.
>
> ***************
>
> "Now, create a file called ResourceMagic.py in your Twisted source
> directoy, and enter the following code:"
>
>
> from zope.interface import implements
>
> from nevow import inevow
>
> ##
> ## How does a request come to the Resource?
> ##
> ## or How to use Nevow without all the fancy automations
> ##
>
> class Root(object):
>     # 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 two methods:
>     # locateChild and renderHTTP.
>     # 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."
>     # For more information see:
>     # http://divmod.org/users/exarkun/nevow-doc/nevow-traversal.html
>     implements(inevow.IResource)
>
>     def locateChild(self, ctx, segments):
>         # This locateChild is 'stupid' since it can only work if the  
> tree of
>         # resources is static. But it will work for our simple example
>         if segments[0] == '':
>             # If the server is looking for the root resource 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 resource has been located we return it with the
> remaining segments
>             # ('baz')
>             return self.foo, segments[1:]
>
>         else:
>             return None, ()
>
>     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.
>         def renderHTTP(self, ctx):
>             return """<html><body>Hello, world!<br />"""
>
> 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, segment[1:]
>         else:
>             return None, ()
>
>     def renderHTTP(self, ctx):
>         return """<html><body><h1 id="heading">You are in Foo</h1>
>         <a href="./foo/baz" id="baz">baz</a></body></html>
> """
>
> class Baz(object):
>     implements(inevow.IResource)
>     def locateChild(self, ctx, segments):
>         return None, ()
>     def renderHTTP(self, ctx):
>         return '<html><body><h1 id="heading">You are in
> Baz</h1></body></html>'
>
> # We are adding children to the resources.
> # This could also happen inside the class.
> root = Root()
> root.foo = Foo()
> root.foo.baz = Baz()
>
>
> "Note," said Dialtone, "That this is the IResource interface from Nevow;
> not the one from twisted.web."
>
> "So now what?" said Turkey.
>
> "At the end of your ResourceMagic.py source file enter:"
>
> from twisted.internet import reactor
> from nevow import appserver
> site = appserver.NevowSite(root)
> reactor.listenTCP(8080, site)
>
> "Hey, I recognize the reactor bit from earlier adventures, " said
> Turkey, "But what's this 'nevow?'"
>
> "Nevow is a web-application construction kit written in Python. Check out
> http://divmod.org/trac/wiki/DivmodNevow. But let's keep our eye on the
> ball here...
>

I'd move this section up, and place it just after the ResourceMagic  
listing.
The code uses inevow.IResource, so I think it is best to clear that up
right away, rather than having Dialtone mention Nevow, go on to another
code snippet and *then* finally explaining what nevow is.

> "To cast the spell, just save the ResourceMagic.py file and enter at the
> console prompt:"
>
> python ResourceMagic.py
>
> "Then point your browser to:"
>
> http://localhost:8080/
>
> "Wait," said Turkey, "Before we run it, I'm still confused by this word
> 'Resource.' When you say, 'Resource,' are you talking about web pages?"
>
> "Could be," said Daniel. "But there are many more kinds of Resources than
> webpages. A Resource is anything that a URI happens to point to --
> anything in cyberspace."
>
> "Well, at least," said Dialtone, "Anything available through the
> designated server."
>
> "Like my favorite Radiohead MP3?" said Turky.
>
> "Anything that gets you through the day," said Daniel. "For more info,
> check out:"
>
> http://en.wikipedia.org/wiki/Resource_(Web)
>
> "...or:"
>
> http://en.wikipedia.org/wiki/Representational_State_Transfer#Resources
>
> "OK," said Turkey, turning to Dialtone. "How's this magic spell of yours
> supposed to work?"
>
> "Well let's run it and see..."
>
>
> Another way to run the code
>
> Another way to run Dialtone's code uses the tac file approach.

I probably sound like a broken record, but I'd suggest offering one, and
only one, way to run the code, so that users aren't fiddling with things
that are not central to grasping the concepts being presented.

Me, I use .tac files for everything these days, so that's what I would
recommend for use within the tutorials.

Keep up the great work, it is inspiring to see someone take this on.

L. Daniel Burr