/Doc/howto/webservers.rst

  1*******************************
  2  HOWTO Use Python in the web
  3*******************************
  4
  5:Author: Marek Kubica
  6
  7.. topic:: Abstract
  8
  9   This document shows how Python fits into the web.  It presents some ways on
 10   how to integrate Python with the web server and general practices useful for
 11   developing web sites.
 12
 13
 14Programming for the Web has become a hot topic since the raise of the "Web 2.0",
 15which focuses on user-generated content on web sites.  It has always been
 16possible to use Python for creating web sites, but it was a rather tedious task.
 17Therefore, many so-called "frameworks" and helper tools were created to help
 18developers creating sites faster and these sites being more robust.  This HOWTO
 19describes some of the methods used to combine Python with a web server to create
 20dynamic content.  It is not meant as a general introduction as this topic is far
 21too broad to be covered in one single document.  However, a short overview of
 22the most popular libraries is provided.
 23
 24.. seealso::
 25
 26   While this HOWTO tries to give an overview over Python in the Web, it cannot
 27   always be as up to date as desired.  Web development in Python is moving
 28   forward rapidly, so the wiki page on `Web Programming
 29   <http://wiki.python.org/moin/WebProgramming>`_ might be more in sync with
 30   recent development.
 31
 32
 33The low-level view
 34==================
 35
 36.. .. image:: http.png
 37
 38When a user enters a web site, his browser makes a connection to the site's
 39webserver (this is called the *request*).  The server looks up the file in the
 40file system and sends it back to the user's browser, which displays it (this is
 41the *response*).  This is roughly how the unterlying protocol, HTTP works.
 42
 43Now, dynamic web sites are not files in the file system, but rather programs
 44which are run by the web server when a request comes in.  They can do all sorts
 45of useful things, like display the postings of a bulletin board, show your
 46mails, configurate software or just display the current time.  These programs
 47can be written in about any programming language the server supports, so it is
 48easy to use Python for creating dynamic web sites.
 49
 50As most of HTTP servers are written in C or C++, they cannot execute Python code
 51in a simple way -- a bridge is needed between the server and the program.  These
 52bridges or rather interfaces define how programs interact with the server.  In
 53the past there have been numerous attempts to create the best possible
 54interface, but there are only a few worth mentioning.
 55
 56Not every web server supports every interface.  Many web servers do support only
 57old, now-obsolete interfaces.  But they can often be extended using some
 58third-party modules to support new interfaces.
 59
 60
 61Common Gateway Interface
 62------------------------
 63
 64This interface is the oldest one, supported by nearly every web server out of
 65the box.  Programs using CGI to communicate with their web server need to be
 66started by the server for every request.  So, every request starts a new Python
 67interpreter -- which takes some time to start up -- thus making the whole
 68interface only usable for low load situations.
 69
 70The upside of CGI is that it is simple -- writing a program which uses CGI is a
 71matter of about three lines of code.  But this simplicity comes at a price: it
 72does very few things to help the developer.
 73
 74Writing CGI programs, while still possible, is not recommended anymore.  With
 75WSGI (more on that later) it is possible to write programs that emulate CGI, so
 76they can be run as CGI if no better option is available.
 77
 78.. seealso::
 79
 80   The Python standard library includes some modules that are helpful for
 81   creating plain CGI programs:
 82
 83   * :mod:`cgi` -- Handling of user input in CGI scripts
 84   * :mod:`cgitb` -- Displays nice tracebacks when errors happen in of CGI
 85     applications, instead of presenting a "500 Internal Server Error" message
 86
 87   The Python wiki features a page on `CGI scripts
 88   <http://wiki.python.org/moin/CgiScripts>`_ with some additional information
 89   about CGI in Python.
 90
 91
 92Simple script for testing CGI
 93^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 94
 95To test whether your web server works with CGI, you can use this short and
 96simple CGI program::
 97
 98    #!/usr/bin/env python
 99    # -*- coding: UTF-8 -*-
100
101    # enable debugging
102    import cgitb
103    cgitb.enable()
104
105    print "Content-Type: text/plain;charset=utf-8"
106    print
107
108    print "Hello World!"
109
110You need to write this code into a file with a ``.py`` or ``.cgi`` extension,
111this depends on your web server configuration.  Depending on your web server
112configuration, this file may also need to be in a ``cgi-bin`` folder, for
113security reasons.
114
115You might wonder what the ``cgitb`` line is about.  This line makes it possible
116to display a nice traceback instead of just crashing and displaying an "Internal
117Server Error" in the user's browser.  This is useful for debugging, but it might
118risk exposing some confident data to the user.  Don't use it when the script is
119ready for production use.  Still, you should *always* catch exceptions, and
120display proper error pages -- end-users don't like to see nondescript "Internal
121Server Errors" in their browsers.
122
123
124Setting up CGI on your own server
125^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
126
127If you don't have your own web server, this does not apply to you.  You can
128check whether if works as-is and if not you need to talk to the administrator of
129your web server anyway. If it is a big hoster, you can try filing a ticket
130asking for Python support.
131
132If you're your own administrator or want to install it for testing purposes on
133your own computers, you have to configure it by yourself.  There is no one and
134single way on how to configure CGI, as there are many web servers with different
135configuration options.  The currently most widely used free web server is
136`Apache HTTPd <http://httpd.apache.org/>`_, Apache for short -- this is the one
137that most people use, it can be easily installed on nearly every system using
138the systems' package management.  But `lighttpd <http://www.lighttpd.net>`_ has
139been gaining attention since some time and is said to have a better performance.
140On many systems this server can also be installed using the package management,
141so manually compiling the web server is never needed.
142
143* On Apache you can take a look into the `Dynamic Content with CGI
144  <http://httpd.apache.org/docs/2.2/howto/cgi.html>`_ tutorial, where everything
145  is described.  Most of the time it is enough just to set ``+ExecCGI``.  The
146  tutorial also describes the most common gotchas that might arise.
147* On lighttpd you need to use the `CGI module
148  <http://trac.lighttpd.net/trac/wiki/Docs%3AModCGI>`_ which can be configured
149  in a straightforward way.  It boils down to setting ``cgi.assign`` properly.
150
151
152Common problems with CGI scripts
153^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
154
155Trying to use CGI sometimes leads to small annoyances that one might experience
156while trying to get these scripts to run.  Sometimes it happens that a seemingly
157correct script does not work as expected, which is caused by some small hidden
158reason that's difficult to spot.
159
160Some of these reasons are:
161
162* The Python script is not marked executable.  When CGI scripts are not
163  executable most of the web servers will let the user download it, instead of
164  running it and sending the output to the user.  For CGI scripts to run
165  properly the ``+x`` bit needs to be set.  Using ``chmod a+x your_script.py``
166  might already solve the problem.
167* The line endings must be of Unix-type.  This is important because the web
168  server checks the first line of the script (called shebang) and tries to run
169  the program specified there.  It gets easily confused by Windows line endings
170  (Carriage Return & Line Feed, also called CRLF), so you have to convert the
171  file to Unix line endings (only Line Feed, LF).  This can be done
172  automatically by uploading the file via FTP in text mode instead of binary
173  mode, but the preferred way is just telling your editor to save the files with
174  Unix line endings.  Most proper editors support this.
175* Your web server must be able to read the file, you need to make sure the
176  permissions are fine.  Often the server runs as user and group ``www-data``,
177  so it might be worth a try to change the file ownership or making the file
178  world readable by using ``chmod a+r your_script.py``.
179* The webserver must be able to know that the file you're trying to access is a
180  CGI script.  Check the configuration of your web server, maybe there is some
181  mistake.
182* The path to the interpreter in the shebang (``#!/usr/bin/env python``) must be
183  currect.  This line calls ``/usr/bin/env`` to find Python, but it'll fail if
184  there is no ``/usr/bin/env``.  If you know where your Python is installed, you
185  can also use that path.  The commands ``whereis python`` and ``type -p
186  python`` might also help to find where it is installed.  Once this is known,
187  the shebang line can be changed accordingly: ``#!/usr/bin/python``.
188* The file must not contain a BOM (Byte Order Mark). The BOM is meant for
189  determining the byte order of UTF-16 encodings, but some editors write this
190  also into UTF-8 files.  The BOM interferes with the shebang line, so be sure
191  to tell your editor not to write the BOM.
192* :ref:`mod-python` might be making problems.  mod_python is able to handle CGI
193  scripts by itself, but it can also be a source for problems.  Be sure you
194  disable it.
195
196
197.. _mod-python:
198
199mod_python
200----------
201
202People coming from PHP often find it hard to grasp how to use Python in the web.
203Their first thought is mostly `mod_python <http://www.modpython.org/>`_ because
204they think that this is the equivalent to ``mod_php``.  Actually it is not
205really.  It does embed the interpreter into the Apache process, thus speeding up
206requests by not having to start a Python interpreter every request.  On the
207other hand, it is by far not "Python intermixed with HTML" as PHP often does.
208The Python equivalent of that is a template engine.  mod_python itself is much
209more powerful and gives more access to Apache internals.  It can emulate CGI, it
210can work an a "Python Server Pages" mode similar to JSP which is "HTML
211intermangled with Python" and it has a "Publisher" which destignates one file to
212accept all requests and decide on what to do then.
213
214But mod_python has some problems.  Unlike the PHP interpreter the Python
215interpreter uses caching when executing files, so when changing a file the whole
216web server needs to be re-started to update.  Another problem ist the basic
217concept -- Apache starts some child processes to handle the requests and
218unfortunately every child process needs to load the whole Python interpreter
219even if it does not use it.  This makes the whole web server slower.  Another
220problem is that as mod_python is linked against a specific version of
221``libpython``, it is not possible to switch from an older version to a newer
222(e.g. 2.4 to 2.5) without recompiling mod_python.  mod_python is also bound to
223the Apache web server, so programs written for mod_python cannot easily run on
224other web servers.
225
226These are the reasons why mod_python should be avoided when writing new
227programs.  In some circumstances it might be still a good idea to use mod_python
228for deployment, but WSGI makes it possible to run WSGI programs under mod_python
229as well.
230
231
232FastCGI and SCGI
233----------------
234
235FastCGI and SCGI try to solve the performance problem of CGI in another way.
236Instead of embedding the interpreter into the web server, they create
237long-running processes which run in the background. There still is some module
238in the web server which makes it possible for the web server to "speak" with the
239background process.  As the background process is independent from the server,
240it can be written in any language of course also in Python.  The language just
241needs to have a library which handles the communication with the web server.
242
243The difference between FastCGI and SCGI is very small, as SCGI is essentially
244just a "simpler FastCGI".  But as the web server support for SCGI is limited
245most people use FastCGI instead, which works the same way.  Almost everything
246that applies to SCGI also applies to FastCGI as well, so we'll only write about
247the latter.
248
249These days, FastCGI is never used directly.  Just like ``mod_python`` it is only
250used for the deployment of WSGI applications.
251
252.. seealso::
253
254   * `FastCGI, SCGI, and Apache: Background and Future
255     <http://www.vmunix.com/mark/blog/archives/2006/01/02/fastcgi-scgi-and-apache-background-and-future/>`_
256     is a discussion on why the concept of FastCGI and SCGI is better that that
257     of mod_python.
258
259
260Setting up FastCGI
261^^^^^^^^^^^^^^^^^^
262
263Depending on the web server you need to have a special module.
264
265* Apache has both `mod_fastcgi <http://www.fastcgi.com/>`_ and `mod_fcgid
266  <http://fastcgi.coremail.cn/>`_.  ``mod_fastcgi`` is the original one, but it
267  has some licensing issues that's why it is sometimes considered non-free.
268  ``mod_fcgid`` is a smaller, compatible alternative. One of these modules needs
269  to be loaded by Apache.
270* lighttpd ships its own `FastCGI module
271  <http://trac.lighttpd.net/trac/wiki/Docs%3AModFastCGI>`_ as well as an `SCGI
272  module <http://trac.lighttpd.net/trac/wiki/Docs%3AModSCGI>`_.
273* nginx also supports `FastCGI
274  <http://wiki.codemongers.com/NginxSimplePythonFCGI>`_.
275
276Once you have installed and configured the module, you can test it with the
277following WSGI-application::
278
279    #!/usr/bin/env python
280    # -*- coding: UTF-8 -*-
281
282    from cgi import escape
283    import sys, os
284    from flup.server.fcgi import WSGIServer
285
286    def app(environ, start_response):
287        start_response('200 OK', [('Content-Type', 'text/html')])
288
289        yield '<h1>FastCGI Environment</h1>'
290        yield '<table>'
291        for k, v in sorted(environ.items()):
292             yield '<tr><th>%s</th><td>%s</td></tr>' % (escape(k), escape(v))
293        yield '</table>'
294
295    WSGIServer(app).run()
296
297This is a simple WSGI application, but you need to install `flup
298<http://pypi.python.org/pypi/flup/1.0>`_ first, as flup handles the low level
299FastCGI access.
300
301.. seealso::
302
303   There is some documentation on `setting up Django with FastCGI
304   <http://www.djangoproject.com/documentation/fastcgi/>`_, most of which can be
305   reused for other WSGI-compliant frameworks and libraries.  Only the
306   ``manage.py`` part has to be changed, the example used here can be used
307   instead. Django does more or less the exact same thing.
308
309
310mod_wsgi
311--------
312
313`mod_wsgi <http://www.modwsgi.org/>`_ is an attempt to get rid of the low level
314gateways.  As FastCGI, SCGI, mod_python are mostly used to deploy WSGI
315applications anyway, mod_wsgi was started to directly embed WSGI aplications
316into the Apache web server.  The benefit from this approach is that WSGI
317applications can be deployed much easier as is is specially designed to host
318WSGI applications -- unlike the other low level methods which have glue code to
319host WSGI applications (like flup which was mentioned before).  The downside is
320that mod_wsgi is limited to the Apache web server, other servers would need
321their own implementations of mod_wsgi.
322
323It supports two modes: the embedded mode in which it integrates with the Apache
324process and the daemon mode which is more FastCGI-like.  Contrary to FastCGI,
325mod_wsgi handles the worker-processes by itself which makes administration
326easier.
327
328
329.. _WSGI:
330
331Step back: WSGI
332===============
333
334WSGI was already mentioned several times so it has to be something important.
335In fact it really is, so now it's time to explain.
336
337The *Web Server Gateway Interface*, :pep:`333` or WSGI for short is currently
338the best possible way to Python web programming.  While it is great for
339programmers writing frameworks, the normal person does not need to get in direct
340contact with it.  But when choosing a framework for web development it is a good
341idea to take one which supports WSGI.
342
343The big profit from WSGI is the unification.  When your program is compatible
344with WSGI -- that means that your framework has support for WSGI, your program
345can be deployed on every web server interface for which there are WSGI wrappers.
346So you do not need to care about whether the user uses mod_python or FastCGI --
347with WSGI it just works on any gateway interface.  The Python standard library
348contains its own WSGI server :mod:`wsgiref`, which is a small web server that
349can be used for testing.
350
351A really great WSGI feature are the middlewares.  Middlewares are layers around
352your program which can add various functionality to it.  There is a `number of
353middlewares <http://wsgi.org/wsgi/Middleware_and_Utilities>`_ already available.
354For example, instead of writing your own session management (to identify a user
355in subsequent requests, as HTTP does not maintain state, so it does now know
356that the requests belong to the same user) you can just take one middleware,
357plug it in and you can rely an already existing functionality.  The same thing
358is compression -- say you want to compress your HTML using gzip, to save your
359server's bandwidth.  So you only need to plug-in a middleware and you're done.
360Authentication is also a problem easily solved using a middleware.
361
362So, generally -- although WSGI may seem complex, the initial phase of learning
363can be very rewarding as WSGI does already have solutions to many problems that
364might arise while writing web sites.
365
366
367WSGI Servers
368------------
369
370The code that is used to connect to various low level gateways like CGI or
371mod_python is called *WSGI server*.  One of these servers is ``flup`` which was
372already mentioned and supports FastCGI, SCGI as well as `AJP
373<http://en.wikipedia.org/wiki/Apache_JServ_Protocol>`_.  Some of these servers
374are written in Python as ``flup`` is, but there also exist others which are
375written in C and can be used as drop-in replacements.
376
377There are quite a lot of servers already available, so a Python web application
378can be deployed nearly everywhere.  This is one big advantage that Python has
379compared with other web techniques.
380
381.. seealso::
382
383   A good overview of all WSGI-related code can be found in the `WSGI wiki
384   <http://wsgi.org/wsgi>`_, which contains an extensive list of `WSGI servers
385   <http://wsgi.org/wsgi/Servers>`_, which can be used by *every* application
386   supporting WSGI.
387
388   You might be interested in some WSGI-supporting modules already contained in
389   the standard library, namely:
390
391   * :mod:`wsgiref` -- some tiny utilities and servers for WSGI
392
393
394Case study: MoinMoin
395--------------------
396
397What does WSGI give the web application developer?  Let's take a look on one
398long existing web application written in Python without using WSGI.
399
400One of the most widely used wiki software is `MoinMoin <http://moinmo.in/>`_.
401It was created in 2000, so it predates WSGI by about three years.  While it now
402includes support for WSGI, older versions needed separate code to run on CGI,
403mod_python, FastCGI and standalone.  Now, this all is possible by using WSGI and
404the already-written gateways.  For running with on FastCGI ``flup`` can be used,
405for running a standalone server :mod:`wsgiref` is the way to go.
406
407
408Model-view-controller
409=====================
410
411The term *MVC* is often heard in statements like "framework *foo* supports MVC".
412While MVC is not really something technical but rather organisational, many web
413frameworks use this model to help the developer to bring structure into his
414program.  Bigger web applications can have lots of code so it is a good idea to
415have structure in the program right from the beginnings.  That way, even users
416of other frameworks (or even languages, as MVC is nothing Python-specific) can
417understand the existing code easier, as they are already familiar with the
418structure.
419
420MVC stands for three components:
421
422* The *model*.  This is the data that is meant to modify.  In Python frameworks
423  this component is often represented by the classes used by the
424  object-relational mapper.  So, all declarations go here.
425* The *view*.  This component's job is to display the data of the model to the
426  user.  Typically this component is represented by the templates.
427* The *controller*.  This is the layer between the user and the model.  The
428  controller reacts on user actions (like opening some specific URL) and tells
429  the model to modify the data if necessary.
430
431While one might think that MVC is a complex design pattern, in fact it is not.
432It is used in Python because it has turned out to be useful for creating clean,
433maintainable web sites.
434
435.. note::
436
437   While not all Python frameworks explicitly support MVC, it is often trivial
438   to create a web site which uses the MVC pattern by separating the data logic
439   (the model) from the user interaction logic (the controller) and the
440   templates (the view).  That's why it is important not to write unnecessary
441   Python code in the templates -- it is against MVC and creates more chaos.
442
443.. seealso::
444
445   The english Wikipedia has an article about the `Model-View-Controller pattern
446   <http://en.wikipedia.org/wiki/Model-view-controller>`_, which includes a long
447   list of web frameworks for different programming languages.
448
449
450Ingredients for web sites
451=========================
452
453Web sites are complex constructs, so tools were created to help the web site
454developer to make his work maintainable.  None of these tools are in any way
455Python specific, they also exist for other programming languages as well.  Of
456course, developers are not forced to use these tools and often there is no
457"best" tool, but it is worth informing yourself before choosing something
458because of the big number of helpers that the developer can use.
459
460
461.. seealso::
462
463   People have written far more components that can be combined than these
464   presented here.  The Python wiki has a page about these components, called
465   `Web Components <http://wiki.python.org/moin/WebComponents>`_.
466
467
468Templates
469---------
470
471Mixing of HTML and Python code is possible with some libraries.  While
472convenient at first, it leads to horribly unmaintainable code.  That's why
473templates exist.  Templates are, in the simplest case, just HTML files with
474placeholders.  The HTML is sent to the user's browser after filling out the
475placeholders.
476
477Python already includes such simple templates::
478
479    # a simple template
480    template = "<html><body><h1>Hello %s!</h1></body></html>"
481    print template % "Reader"
482
483The Python standard library also includes some more advanced templates usable
484through :class:`string.Template`, but in HTML templates it is needed to use
485conditional and looping contructs like Python's *for* and *if*.  So, some
486*template engine* is needed.
487
488Now, Python has a lot of template engines which can be used with or without a
489`framework`_.  Some of these are using a plain-text programming language which
490is very easy to learn as it is quite limited while others use XML so the
491template output is always guaranteed to be valid XML.  Some `frameworks`_ ship
492their own template engine or recommend one particular.  If one is not yet sure,
493using these is a good idea.
494
495.. note::
496
497   While Python has quite a lot of different template engines it usually does
498   not make sense to use a homebrewed template system.  The time needed to
499   evaluate all templating systems is not really worth it, better invest the
500   time in looking through the most popular ones.  Some frameworks have their
501   own template engine or have a recommentation for one.  It's wise to use
502   these.
503
504   Popular template engines include:
505
506   * Mako
507   * Genshi
508   * Jinja
509
510.. seealso::
511
512   Lots of different template engines divide the attention between themselves
513   because it's easy to create them in Python.  The page `Templating
514   <http://wiki.python.org/moin/Templating>`_ in the wiki lists a big,
515   ever-growing number of these.
516
517
518Data persistence
519----------------
520
521*Data persistence*, while sounding very complicated is just about storing data.
522This data might be the text of blog entries, the postings of a bulletin board or
523the text of a wiki page.  As always, there are different ways to store
524informations on a web server.
525
526Often relational database engines like `MySQL <http://www.mysql.com/>`_ or
527`PostgreSQL <http://http://www.postgresql.org/>`_ are used due to their good
528performance handling very large databases consisting of up to millions of
529entries.  These are *queried* using a language called `SQL
530<http://en.wikipedia.org/wiki/SQL>`_.  Python programmers in general do not like
531SQL too much, they prefer to work with objects.  It is possible to save Python
532objects into a database using a technology called `ORM
533<http://en.wikipedia.org/wiki/Object-relational_mapping>`_.  ORM translates all
534object-oriented access into SQL code under the hood, the user does not need to
535think about it.  Most `frameworks`_ use ORMs and it works quite well.
536
537A second possibility is using files that are saved on the hard disk (sometimes
538called flatfiles).  This is very easy, but is not too fast.  There is even a
539small database engine called `SQLite <http://www.sqlite.org/>`_ which is bundled
540with Python in the :mod:`sqlite` module and uses only one file.  This database
541can be used to store objects via an ORM and has no other dependencies.  For
542smaller sites SQLite is just enough.  But it is not the only way in which data
543can be saved into the file systems.  Sometimes normal, plain text files are
544enough.
545
546The third and least used possibility are so-called object oriented databases.
547These databases store the *actual objects* instead of the relations that
548OR-mapping creates between rows in a database.  This has the advantage that
549nearly all objects can be saven in a straightforward way, unlike in relational
550databases where some objects are very hard to represent with ORMs.
551
552`Frameworks`_ often give the users hints on which method to choose, it is
553usually a good idea to stick to these unless there are some special requirements
554which require to use the one method and not the other.
555
556.. seealso::
557
558   * `Persistence Tools <http://wiki.python.org/moin/PersistenceTools>`_ lists
559     possibilities on how to save data in the file system, some of these modules
560     are part of the standard library
561   * `Database Programming <http://wiki.python.org/moin/DatabaseProgramming>`_
562     helps on choosing a method on how to save the data
563   * `SQLAlchemy <http://www.sqlalchemy.org/>`_, the most powerful OR-Mapper for
564     Python and `Elixir <http://elixir.ematia.de/>`_ which makes it easier to
565     use
566   * `SQLObject <http://www.sqlobject.org/>`_, another popular OR-Mapper
567   * `ZODB <https://launchpad.net/zodb>`_ and `Durus
568     <http://www.mems-exchange.org/software/durus/>`_, two object oriented
569     databases
570
571
572.. _framework:
573
574Frameworks
575==========
576
577As web sites can easily become quite large, there are so-called frameworks which
578were created to help the developer with making these sites.  Although the most
579well-known framework is Ruby on Rails, Python does also have its own frameworks
580which are partly inspired by Rails or which were existing a long time before
581Rails.
582
583Two possible approaches to web frameworks exist: the minimalistic approach and
584the all-inclusive approach (somtimes called *full-stack*). Frameworks which are
585all-inclusive give you everything you need to start working, like a template
586engine, some way to save and access data in databases and many features more.
587Most users are best off using these as they are widely used by lots of other
588users and well documented in form of books and tutorials.  Other web frameworks
589go the minimalistic approach trying to be as flexible as possible leaving the
590user the freedom to choose what's best for him.
591
592The majority of users is best off with all-inclusive framewors.  They bring
593everything along so a user can just jump in and start to code.  While they do
594have some limitations they can fullfill 80% of what one will ever want to
595perfectly.  They consist of various components which are designed to work
596together as good as possible.
597
598The multitude of web frameworks written in Python demonstrates that it is really
599easy to write one.  One of the most well-known web applications written in
600Python is `Zope <http://www.zope.org/>`_ which can be regarded as some kind of
601big framework.  But Zope was not the only framework, there were some others
602which are by now nearly forgotten.  These do not need to be mentioned anymore,
603because most people that used them moved on to newer ones.
604
605
606Some notable frameworks
607-----------------------
608
609There is an incredible number of frameworks, so there is no way to describe them
610all.  It is not even necessary, as most of these frameworks are nothing special
611and everything that can be done with these can also be done with one of the
612popular ones.
613
614
615Django
616^^^^^^
617
618`Django <http://www.djangoproject.com/>`_ is a framework consisting of several
619tightly coupled elements which were written from scratch and work together very
620well.  It includes an ORM which is quite powerful while being simple to use and
621has a great online administration interface which makes it possible to edit the
622data in the database with a browser.  The template engine is text-based and is
623designed to be usable for page designers who cannot write Python.  It supports
624so-called template inheritance and filters (which work like Unix pipes).  Django
625has many handy features bundled, like creation of RSS feeds or generic views
626which make it possible to write web sites nearly without any Python code.
627
628It has a big, international community which has created many sites using Django.
629There are also quite a lot of add-on projects which extend Django's normal
630functionality.  This is partly due to Django's well written `online
631documentation <http://doc.djangoproject.com/>`_ and the `Django book
632<http://www.djangobook.com/>`_.
633
634
635.. note::
636
637   Although Django is an MVC-style framework, it calls the components
638   differently, which is described in the `Django FAQ
639   <http://www.djangoproject.com/documentation/faq/#django-appears-to-be-a-mvc-framework-but-you-call-the-controller-the-view-and-the-view-the-template-how-come-you-don-t-use-the-standard-names>`_.
640
641
642TurboGears
643^^^^^^^^^^
644
645The other popular web framework in Python is `TurboGears
646<http://www.turbogears.org/>`_.  It takes the approach of using already existing
647components and combining them with glue code to create a seamless experience.
648TurboGears gives the user more flexibility on which components to choose, the
649ORM can be switched between some easy to use but limited and complex but very
650powerful.  Same goes for the template engine.  One strong point about TurboGears
651is that the components that it consists of can be used easily in other projects
652without depending on TurboGears, for example the underlying web server CherryPy.
653
654The documentation can be found in the `TurboGears wiki
655<http://docs.turbogears.org/>`_, where links to screencasts can be found.
656TurboGears has also an active user community which can respond to most related
657questions.  There is also a `TurboGears book <http://turbogearsbook.com/>`_
658published, which is a good starting point.
659
660The plan for the next major version of TurboGears, version 2.0 is to switch to a
661more flexible base provided by another very flexible web framework called
662`Pylons <http://pylonshq.com/>`_.
663
664
665Other notable frameworks
666^^^^^^^^^^^^^^^^^^^^^^^^
667
668These two are of course not the only frameworks that are available, there are
669also some less-popular frameworks worth mentioning.
670
671One of these is the already mentioned Zope, which has been around for quite a
672long time.  With Zope 2.x having been known as rather un-pythonic, the newer
673Zope 3.x tries to change that and therefore gets more acceptance from Python
674programmers.  These efforts already showed results, there is a project which
675connects Zope with WSGI called `Repoze <http://repoze.org/>`_ and another
676project called `Grok <http://grok.zope.org/>`_ which makes it possible for
677"normal" Python programmers use the very mature Zope components.
678
679Another framework that's already been mentioned is `Pylons`_.  Pylons is much
680like TurboGears with ab even stronger emphasis on flexibility, which is bought
681at the cost of being more difficult to use.  Nearly every component can be
682exchanged, which makes it necessary to use the documentation of every single
683component, because there are so many Pylons combinations possible that can
684satisfy every requirement.  Pylons builds upon `Paste
685<http://pythonpaste.org/>`_, an extensive set of tools which are handy for WSGI.
686
687And that's still not everything.  The most up-to-date information can always be
688found in the Python wiki.
689
690.. seealso::
691
692   The Python wiki contains an extensive list of `web frameworks
693   <http://wiki.python.org/moin/WebFrameworks>`_.
694
695   Most frameworks also have their own mailing lists and IRC channels, look out
696   for these on the projects' websites.  There is also a general "Python in the
697   Web" IRC channel on freenode called `#python.web
698   <http://wiki.python.org/moin/PoundPythonWeb>`_.