web-overview.xhtml [plain text]

<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Overview of Twisted Web</title>
  </head>

  <body>
    <h1>Overview of Twisted Web</h1>

    <h2>Introduction</h2>

    <p>Twisted Web is a web application server written in pure
    Python, with APIs at multiple levels of abstraction to
    facilitate different kinds of web programming.
    </p>

    <h2>Twisted Web's Structure</h2>

        <p><img src="../img/web-overview.png"/></p>

        <p>When
        the Web Server receives a request from a Client, it creates
        a Request object and passes it on to the Resource system.
        The Resource system dispatches to the appropriate Resource
        object based on what path was requested by the client. The
        Resource is asked to render itself, and the result is
        returned to the client.</p>

    <h2>Resources</h2>

    <p>Resources are the lowest-level abstraction for applications
    in the Twisted web server. Each Resource is a 1:1 mapping with
    a path that is requested: you can think of a Resource as a
    single <q>page</q> to be rendered. The interface for making
    Resources is very simple; they must have a method named
    <code>render</code> which takes a single argument, which is the
    Request object (an instance of <code
    class="API">twisted.web.server.Request</code>). This render
    method must return a string, which will be returned to the web
    browser making the request. Alternatively, they can return a
    special constant, <code
    class="API">twisted.web.server.NOT_DONE_YET</code>, which tells
    the web server not to close the connection; you must then use
    <code class="python">request.write(data)</code> to render the
    page, and call <code class="python">request.finish()</code>
    whenever you're done.
    </p>

    <h2>
	Web programming with Twisted Web
    </h2>

    <p>
	Web programmers seeking a higher level abstraction than the Resource system
	should look at <a href="http://www.divmod.org/Home/Projects/Nevow/">Nevow</a>, available as
	part of the <a href="http://www.divmod.org/Quotient/">Quotient</a> project. Nevow
	is not distributed as part of Twisted.
    </p>

    <p>
	Nevow is based on the same ideas as the earlier <a href="woven.xhtml">Woven</a> framework.
	Woven only remains part of Twisted in order to support existing projects, and should
	not be used for new projects. Nevow is a simpler framework which retains the strengths of Woven.
    </p>
  </body>
</html>