Well, after trying twice before, I think I didn't actually make it clear what Paste is. I don't know if I've done any better this time, but I'll keep trying. I'm not sure entirely what the confusion is -- in part Paste is several disconnected things, in part I think people read more into it than there is (it's not any Deep New Ideas), or maybe I'm leaving out important details. Feedback welcome. The canonical location for this document is http://pythonpaste.org/docs/what-is-paste.html and copied here for all you RSS readers...
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.
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...
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.
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:
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.
All code has to go somewhere. Sometimes there's not a good location for that code. So it can go in Paste.
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).
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.
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.
One facility in Paste is paste-setup 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, paste-setup can provide other commands. For instance in a webkit_zpt application paste-setup 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.
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 paste-setup 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).
I've been following the work on Paste on svn, and missed two things, the first on is this explanation (I think it can use some more examples, though) and another one is a ChangeLog file for tracking development. Is this last one awkward to work with? Thanks for the good work!
# pachi
I guess I've never really kept a change log for any project I've done. I try to keep good svn log messages, and paste-checkins will let you track that. Once there are releases I want to keep a news file for significant API changes (which is generally much easier to track than a change log). The bug tracker should keep track of some other details. I'm not sure exactly where a change log fits into that.
Oh, I wasn't aware of that one. Maybe it could be possible to pipe the check-in messages into a ChangeLog style file so those check-in messages can be read without svn or an avaliable connection... Maybe I'm too lazy, or too used to a way of doing things, but I track quite a bunch of projects and I use to read the ChangeLogs to see what has been going on and when something appealing catches my attention I give it a closer look. I just thought that would make some people track Paste more closely... and it deserves it :)
I should create an RSS feed from it using this: http://svn.pythonfr.org/public/pythonfr/utils/subversion/subverssed.py
Otherwise svn log can show you cumulative log messages.
Sorry, but I still don't get it. Parts of paste are clearer to me now, but overall, not very. I'd like to help improve this document. What's the best way to do this? Can you put it on a wiki and let me hack on it?
I just came here from a link on the Python Daily URL. This doesn't really explain it for me. Sometimes when I write documentation, I try to address who the reader is and what they're used to seeing, which often means separate paragraphs (or even chapters) for the particular audience.
Myself, I use Python and Java to write (non-web) applications, and Apache + PHP to write web sites & web applications. So for me, I was basically lost by the second paragraph.
I guess you're assuming knowledge of WSGI. Maybe the introduction needs a sentence like "Before trying to understand what Paste is, you should know what WSGI is (link to a _What_is_WSGI_ document)"
# sjbrown
Mmm... you are probably right. Right now it's really directed to people who have experience with Python web frameworks. But that should be explicit, otherwise people without that experience will just be discouraged.
IMHO a better bet will be to direct it to people with little experience. A developer experienced in python web frameworks will be less impressed, he/she will have a lot of habits acquired in the other frameworks, will be more reluctant to change and Paste has to be really really good to impress him.
A beginner caries a lot less baggage. He will give Paste 10, 20 maybe 30 min. and if in that time Paste impresses him there is a good chance he will use it.
I'm a beginner and I see "Zope Page Templates", beside the fact that I get scared by the word Zope when I look at the mini introduction to TAL I'm thinking "What the heck is this?" a beginner will see to much information, a seasoned programmer will see redundancy.
In my view Paste will be better served using something like HTMLTemplate http://freespace.virgin.net/hamish.sanderson/htmltemplate.html, it is simple, powerful and did I mentioned simple? Yeah simple, how simple? well... copying one .py file somewhere in the PYTHONPATH takes care of the installation. Using it is just as simple.
Take the beginner from A to Z, show him a quick install, a simple example, a simple but not trivial example, a complex example and of course provide value. For example if John Doe were to install Paste and instantly get a Wiki and a blog or a bliki as a bonus (complete with 2-3 nice CSS designs) all validating, RSS/Atom enabled, all the bells and whistles John Doe will be very happy, he will recommend Paste to all his friends. He might not care that is python as long as it works or maybe he just discovered python and wants to use it in everything or maybe he is like me... hateing PHP syntax.
Go after the beginners! there are a lot more of them than seasoned programmers, they might be more forgiving especially if you put up a big sign saying "Alpha" and if they can do it... seasoned programmers will have no other excuse not to at least try it.
# Peter Damoc
That was my feeling too knowing nothing about WSGI... I read all 3 of your attempts to explain Paste and I think this one is much better than the ones before but still maybe not basic enough...
Maybe a bit more structure would help as well, it might be just me but some more headlines, a kind of table of contents even for an article as short as this would help. There something like "What is WSGI", "How does a server fit in", etc could fit in.
I guess an example of a specific server + paste + application (that's the way it works, is it not?) like apache + paste + ? would also show more than a lot of explaining.
I read your stuff quite frequently and always wonder how you find the time to actually do stuff and at the same time read/investigate/try in all other web frameworks and other tools... That's actually something you seem to assume from the casual reader. I do read a lot about some of the (it seems) 100s of Python web frameworks but have not been able to try one as there are so many and I am always looking for a really good solution Paste might be to get to.
Just some ideas, actually writing a good documentation and explaining what something is for all kinds of users is very difficult... (something I am experiencing myself at the moment)
# Chris
I was just trying to get the energy together to lurn Zope3 when I saw this nice, literate looking exercise. Though I don't understand it.
One thing you don't mention is persistence. This is a key feature of what i think are probably the top three competing python frameworks - zope with ZODB, sqlobject with subway and atop with the twisted/nevow/quotient stuff.
What's your plan for persistence with paste?