What Is Paste? ============== :author: Ian Bicking :revision: $Rev$ :date: $LastChangedDate$ Introduction ------------ It has come up several times that people don't understand quite what Paste is and what it is intended to be. This document is an attempt to respond to that. In part the confusion has been because Paste has is really several things. It is an attempt to fill in some of the gaps in web frameworks, and to identify places where things can be shared; as such it is a reaction to the current state of frameworks, and a direct attempt to be complimentary to those frameworks. As a result it can be somewhat eclectic. Server/Application Glue ----------------------- `WSGI `_ defines how servers invoke applications, and how application respond. However, it does not define how servers or applications come into existance, or how they are passed to each other. Paste is meant to bridge that, but providing a single entry point that can create and configure a server, create an WSGI application, and hook the two together. This generally involves distinct code for each server supported, since there isn't any standard. Also, Paste is expected to create the applications that get served. This is typically done through at least somewhat-custom code that is driven by the configuration. Which leads us to... Configuration ------------- In order to set up servers and application, some kind of configuration is needed. Paste loads up configuration files and makes these available to all parts of the system. One goal of Paste is to support small pieces of decoupled code that work together. This is part of its WSGI-driven architecture. However, exactly how that code is split up is an implementation detail that really shouldn't be exposed to end users. Because of this, each component can't have its own configuration without resulting in a mess of configuration files and formats that are fragile and difficult to understand. This configuration is accessible from all portions of the system, so your application configuration can go in beside server and middleware configuration. Reusable Middleware ------------------- WSGI allows for the idea of "middleware" -- something that is both a server and an application. This is similar to a filter or a wrapper. By building these on WSGI, they are neutral with respect to any particular framework. Use of the middleware is generally optional, but they serve as a way to share work, and tend to be a fairly good architecture for many problems. Some of the middleware included: * Adding configuration information to the request (``paste.configmiddleware``) * Catching and reporting errors (``paste.error_middleware``) * Catching HTTP-related exceptions and producing HTTP responses (``paste.httpexceptions``) * Testing for WSGI compliance (``paste.lint``) * Identifying and authenticating user logins (``paste.login``) * Facilitating internal redirects and recursive calls (``paste.recursive``) * Adding sessions to the request (``paste.session``) * Validating HTML output from applications (``paste.wdg_validate``) Another kind of middleware is one which finds and constructs applications. At the moment, just one such middleware is in the library: ``paste.urlparser``. This looks on disk for files and Python modules, and creates WSGI applications from them. Other URL resolvers are also possible, e.g., one that traverses objects, or uses explicit URL->application maps. Otherwise Homeless Code ----------------------- All code has to go somewhere. Sometimes there's not a good location for that code. So it can go in Paste. An Implementation Webware ~~~~~~~~~~~~~~~~~~~~~~~~~ ``paste.webkit`` is a reimplementation of Webware built on the Paste middleware. This is a fairly thin implementation, mostly mapping the middleware APIs to Webware APIs. In this system Webware Servlet instances become WSGI applications (``paste.webkit.wkservlet.Servlet.__call__`` implements a WSGI application). Reloader ~~~~~~~~ This module (``paste.reloader``) checks in the background for modified files (typically modules in ``sys.modules``) and restarts the entire server when that happens. This avoids the stale-code issue, where code in memory gets out of sync with code on disk. When that happens confusion can ensue. Manually restarting is also somewhat annoying, so this does the restarting for you. It's not really appropriate for a live deployment, but it works well in development. Documentation System ~~~~~~~~~~~~~~~~~~~~ This is still young and not well defined, but there's some work on using `doctest `_ to generate and test documentation. These can turn into a kind of acceptance test. Application Templates --------------------- One facility in Paste is ``paster`` a script to create application "templates". Basically an empty application, with a little structure. For instance, the Webware/Zope Page Template (webkit_zpt) application template sets up these files:: __init__.py server.conf sitepage.py templates/standard_template.pt templates/index.pt web/__init__.py web/index.py web/static/stylesheet.css This is a kind of a minimal set up for a typical web application using these systems. After the application is set up, ``paster`` can provide other commands. For instance in a webkit_zpt application ``paster servlet edit`` will create ``web/edit.py`` and ``web/edit.pt`` files. Each template has control implement any commands how it sees fit, but some convenient functions and classes are provided to make implementation easier. Distribution ------------ This is still an open issue, but I hope Paste will facilitate installation of multiple frameworks quickly. Some of this is handled already: ``paste-server`` starts a server easily and quickly, and ``paster`` gives a user the basis for an application quickly. Actual software installation is a little harder. Right now the plan is to use `Python Eggs `_, but it's just a plan. Python Eggs are still in development (though usable), and it requires creating packages for each project (which is feasible, but requires a fair amount of grunt work).