[Twisted-Python] Getting Stories Straight (RPYs)

[Moshe Zadka]

On 24 Jun 2003, Philippe <lafou at wanadoo.fr> wrote:

> RPY seems to be a good starting point to me.

It isn't. That was itamar's point: don't use RPYs. It's not that they
are not useful, but...
OK, here's an analogy. When teaching kids correct table manners, you put
books under their arms, and tell them not to let the books fall. It's not
that being able to hold books while eating is a useful skill -- it's that
the books force the kid to constrain the movements of his hands.

In a similar way, not using RPYs will force you to think about the
correct way to build your application. If you feel yourself forced
to use RPY *avoid the temptation*, and know that what you're feeling
is actually a way to build the application *incorrectly*. If you're
still not sure what to do, ask advice -- here or on #twisted. But
in no case succumb to the "just write RPYs".

You should only use RPY when you are able to build applications without
RPYs. This is why you see tools like Issues, say, use RPYs -- notice
how you *can* use Issues *without* RPYs.

> If I understand it well, I should have :
> 
> - xhtml templates.
> - xhtml macro templates eventually.
> - rpy files.
> - py files.

NO!
You should *not* have RPY files
Some Python modules will be used for pure, non-web-related business
logic. Some Python modules will define resource trees which bind
together logic and presentation, for example by using Page instances
and defining wchild_* methods. Perhaps you'll find a need to write
an ApplicationService which holds various resources, usually not.
Notice the one thing missing from this paragraph: .rpy files. That's
right, you should not have *any* .rpy files. You *may* have need for
Python modules with long and tortorous functions like:

def buildBlogResource(
  realName,
  numberOfArticles,
  numberOfLines,
  colorScheme,
  ....
  ):
    blogObject = blog.DataRespository(...)
    root = blog.rootResource(blogObject)
    showArticles = blog.Show(blogObject)
    root.putChild('show', showArticles)
    # Notice how I use relative URLs here:
    updateArticlesForm = blog.UpdateForm(blogObject, url="doupdate")
    root.putChild('update', updateArticles)
    doUpdate = blog.DoUpdate(blogObject)
    root.putChild('doupdate', doUpdate)
    return root
    
But there should be *no* RPYs. Now, when testing, you might use a script
similar to

"""
#!/usr/bin/python2.2
from blog import buildBlogResource
from twisted.web import server
from twisted.internet import reactor

resource = buildBlogResource("Moshe", 10, 20, "RED", ...)
reactor.listenTCP(8080, server.Site(resource))
"""

When you are done testing, you package your Python library. Now,
you may do several things:

1. Put a .rpy in your doc/examples which looks something like

"""
# change these lines to configure
name = "Moshe"
articles = 10
lines = 20
colorScheme = "RED"
...

# touch nothing below this line
from blog import buildBlogResource
resource = buildBlogResource(name, articles, lines, colorScheme, ...)
"""

2. Write a TAP plugin to easily generate blogs. See plugin.html for
   full details, I'll show an excerpt here:

""""
from blog import buildBlogResource

def updateApplication(app, config):
    name, articles, lines, colorScheme = (config['name'], config['articles'],
                                   config['lines'], config['colorScheme]')
    resource = buildBlogResource(name, articles, lines, colorScheme, ...)
    app.listenTCP(config['port'], server.Site(resource))
"""

Your users can now do

% mktap myblog --name=Moshe --colorScheme=RED
% twistd -f myblog

3. Supply a twisted-web Debian plugin, which looks like

"""
# change these lines to configure
name = "Moshe"
articles = 10
lines = 20
colorScheme = "RED"
...

# touch nothing below this line
from blog import buildBlogResource
resource = buildBlogResource(name, articles, lines, colorScheme, ...)
default.putChild('myblog', resource)
"""

Sitting in /etc/twisted-web/local.d/99myblog.py

4. Document buildBlogResource in your API docs, so savvy Twisted programmers
   can deliver more and better ways to integrate it with a Python app.
   For example, writing through-the-web management to add a blog to a site.

5. Write TRPs (Twisted Resource Pickles) command-line generators.

etc. etc. etc.

Please notice when the RPY arrived on the scene: a long time after
you had a fully functioning blog, and you were *documenting* it. This
is the proper time to think about deployment issues.
-- 
Moshe Zadka -- http://moshez.org/
Buffy: I don't like you hanging out with someone that... short.
Riley: Yeah, a lot of young people nowadays are experimenting with shortness.
Agile Programming Language -- http://www.python.org/