Commits

Robert Brewer committed dcfac82

Docs: cleaned up some refs

Comments (0)

Files changed (5)

sphinx/source/appendix/choosingtemplate.rst

-.. _ChoosingATemplatingLanguage:
-
-******************************
-Choosing a templating language
-******************************
-
-CherryPy is an open-ended Web framework that integrates with a wide variety of templating systems. This document is to help you choose which one is right for you.
-
-Cheetah
-=======
-
-.. tabularcolumns:: |l|c|l|
-
-================= ================ ================
-Feature           Supported        Comment
-================= ================ ================
-Caching           [X]              You can compile templates into python classes.
-Speed             moderate         Not a speed demon. But critical part of the library (the namemapper) is also available as binary for linux, windows and makes for great performance improvement
-Wysiwyg           [ ]              No. Use any text editor  
-Flexibility       Great
-Pythonic design   [X]              Very much so, it can use python constructs in the template
-Pure python       Yes
-XML Syntax        [ ]              Thank heavens no!
-Language elements                  See the `Cheetah <http://www.cheetahtemplate.org/>`_ docs
-Learning curve    very short
-Community         Large
-Summary:                           Cheetah is one of the simplest and most comprehensive templating engines you'll find. Excellent documentation.
-================= ================ ================
-
-
-
-ClearSilver
-===========
-
-====================  ============  ==================
-Feature               Supported     Comment
-====================  ============  ==================
-Caching               [ ]           
-Speed                               ''Untested, we don't have a benchmark yet''     
-Wysiwyg               [ ]           No. Use any text editor     
-Targets               All       
-Flexibility           Great           
-Pythonic design       []            Written in c, includes drivers for python, ruby, perl, and java     
-CherryPy Integration  []           
-Pure python           No           
-XML Syntax            [X]           
-Language elements                   See the `ClearSilver <http://www.clearsilver.net/docs/>`_ docs     
-Learning curve        short           
-Community             Small           
-i18n                  [ ]           
-Summary:                            ClearSilver uses a dataset driven approach which completely separates layout and application logic.     
-====================  ============  ==================
-
-`Genshi <http://genshi.edgewall.org>`_
-=======================================
-
-See the `Genshi tutorial <http://tools.cherrypy.org/wiki/Genshi>`_.
-
-==================== =============== ==================
-Feature              Supported       Comment    
-==================== =============== ==================
-Caching              [X]             
-Speed                                `Genshi performance <http://genshi.edgewall.org/wiki/GenshiPerformance>`_
-WYSIWYG              [X]             If you're using a XHTML Compliant WYSIWYG editor.
-Targets              XML or Text     Only used for outputting structured text files or XML based files such as XHTML 
-Flexibility          Great           
-Pythonic design      [X]          
-CherryPy Integration [X]             `Genshi Tutorial with CherryPy <http://genshi.edgewall.org/wiki/GenshiTutorial>`_
-Pure python          [X]           
-XML Syntax           [X]             XHTML + additional namespaces     
-Language elements                    XHTML + additional tags and inline Python.  See `Genshi's Documentation <http://genshi.edgewall.org/wiki/Documentation/index.html>`_.
-Learning curve       short           Do you know XHTML?  Then you're 75% of the way there!
-Community            Growing         Trac and `TurboGears <http://www.turbogears.org/>`_ (via `ToscaWidgets <http://toscawidgets.org/>`_) are both moving to Genshi.
-i18n                 [X]             
-Summary:                             Plain XHTML templates make Genshi easy to use even for web designers who don't know Python.  Its considered by many to be the successor to Kid.
-==================== =============== ==================
-
-Kid
-===
-
-HTMLTemplate
-============
-
-Nevow
-=====
-
-PSP
-===
-
-PyMeld
-======
-
-===================== ========== ===============
-Feature               Supported  Comment       
-===================== ========== ===============
-Caching               [ ]        Left to the user.      
-Speed                            ''Untested, we don't have a benchmark yet''     
-Wysiwyg               [X]        Templates are pure HTML/XHTML and can contain dummy content     
-Targets               All       
-Flexibility                      HTML-ish markup only. No other formats.           
-Pythonic design       [X]        Very.     
-CherryPy Integration  [ ]           
-Pure python           Yes           
-XML Syntax            [ ]        Not really. Relies on "id" attributes in HTML/XHTML.     
-Language elements                See the `PyMeld docs <http://www.entrian.com/PyMeld/>`_     
-Learning curve                   Gentle and short            
-Community                        `None <http://www.google.com/search?q=%22pymeld+users%22>`_           
-i18n                  [ ]        Left to user      
-Summary:                         Elegant and unique tool for manipulating HTML in a Pythonic way. Any (X)HTML element with an "id" attribute can be manipulated -- including cloning, deletion, or attribute changing.     
-===================== ========== ===============
-
-
-XSLT
-====
-
-===================== ============== =====================
-Feature               Supported      Comment       
-===================== ============== =====================
-Caching               [ ]            None but the Picket filter has a basic cache.      
-Speed                                ''Untested, we don't have a benchmark yet''     
-Wysiwyg               [ ]            No. Use any text editor or specific XSL editor     
-Targets               All       
-Flexibility           Great           
-Pythonic design       [ ]            It's totally language/platform independent     
-CherryPy Integration  [X]            [wiki:Picket Picket] is a filter implementation using the `4Suite <http://4suite.org>`_ framework     
-Pure python           No           
-XML Syntax            [X]           
-Language elements                    See the `XSLT <http://www.w3.org/TR/xslt>`_ doc     
-Learning curve        Depends on you XSLT is quite a big beast but you will find plenty of documentation      
-Community             Big           
-i18n                  [X]           
-Summary:                             It's a standard. XSLT is fantastic if you are mainly using XML documents. It's also totally language and platform independent and therefore you will not have to learn a new templating language if you change your programming language.    
-===================== ============== =====================
-
-Xyaptu
-======
-
-===================== ============== =====================
-Feature               Supported      Comment       
-===================== ============== =====================
-Caching               [ ]            Only if there is a !DoneByMyselfImplementation. - xyaptu is a templating unit, nothing more..      
-Speed                                ''Untested, we don't have a benchmark yet''     
-Wysiwyg               [ ]            Nope: Nano, vim, emacs, notepad.... but by using xmlstyle tags, the language is designed not to interfere with graphical design software (as long as this software will also leave in unknown tags that is)    
-Targets               anything       Whether it be javascript, xml, html, python, csv or whatever you want. 
-Flexibility           no complaints  Loops, conditions, not target language dependent     
-Pythonic design       [X]            Using dictionaries, tuples, strings and generators     
-CherryPy Integration  [X]            There is a filter built on top of CherryPy, including samples etc     
-Pure python           [X]            all the way. 3 modules: the Filter, Xyaptu and Yaptu - works everywhere     
-Language elements     7              See the XyaptuFilter, subsection Markup-syntax     
-Learning curve        curve?         Hardly any. The filter might be the toughest part (say, 5 minutes?)      
-Community             Tiny           Too bad, but it's the truth     
-i18n                  [X]            not using the i18n module though. Xyaptu is based on Document Name Spaces, this is a regular dictionary. The keys are in your template, and will be replaced with the values in this dictionary. So having multiple dictionaries (one for each language) is enough.. It's not perfect, but at least it's something usefull :)      
-Summary:                             see: XyaptuFilter [[br]] Xyaptu stands for: eXtended  Yet Another Python Templating Unit    
-===================== ============== =====================
-
-ZPT
-===
-
-===================== ============== =====================
-Feature               Supported      Comment       
-===================== ============== =====================
-Caching               [ ]            ''Unknown''          
-Speed                 [ ]          
-WYSIWYG               [ ]            XHTML can be edited in a WYSIWYG editor, with scripting is placed in an XML namespace for tags and attributes     
-Targets               XML            Includes XHTML and other XML formats (SVG, MathML, etc.)    
-Pythonic design       [ ]          
-Flexibility               
-CherryPy Integration               
-Pure Python           [X]          
- XML Syntax           [X]           
-Language Elements                    See `ZPT Documentation <http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/AppendixC.stx>`_     
-Learning Curve        Medium         Learning curve depends on knowledge of Python and XML    
-Community             Medium         `Zope <http://www.zope.org/>`_ depends on ZPT, so community support is readily available.     
-i18n                  Unknown        i18n features are available in the Zope framework, but may not work outside of Zope.     
-Summary                              Zope Page Templates are relatively easy for web designers to edit without disturbing scripting already embedded in the page. The basic syntax tends to be clean and simple, while more complex tasks are possible. However, ZPT can only be used with XML documents, not other text-based documents such as CSS or JavaScript.     
-===================== ============== =====================
-
-py.xml
-======
-
-===================== ============== =====================
-Feature               Supported      Comment       
-===================== ============== =====================
-Caching               [ ]            ''None''          
-Speed                 [ ]          
-WYSIWYG               [ ]            No. Use any text editor     
-Targets               XML            Includes XHTML and other XML formats (SVG, MathML, etc.)    
-Pythonic design       [X]            py.xml is designed to be a Python to generating XML     
-Flexibility               
-CherryPy Integration               
-Pure Python           [X]          
- XML Syntax           [ ]            No. All code is generated with Python calls     
-Language Elements               
-Learning Curve        None           If you can do Python you can do py.xml     
-Community             Unknown           
-i18n                  None           You will have to provide i18n yourself     
-Summary                              The py lib offers a pythonic way to generate xml/html, based on ideas from xist which uses python class objects to build xml trees. However, xist's implementation is somewhat heavy because it has additional goals like transformations and supporting many namespaces. But its basic idea is very easy.     
-===================== ============== =====================
-
-Old/Unmaintained
-================
-
-CherryTemplate
---------------
-
-See http://cherrytemplate.python-hosting.com/

sphinx/source/appendix/faq.rst

       Have a look at this page (CP 2.0): [wiki:CherryPySpeed CherryPy speed]
 
   * When will it be added to the standard python library?
-      Probably never. The standard python library is not the place to distribute an application server.
+      Probably never. The standard python library is not the place to distribute
+      an application server.
 
   * Who uses CherryPy?
     See :ref:`SuccessStories`.
       You can use the virtual host filter as described [wiki:VirtualPathFilter here].
 
   * Does CherryPy support https?
-      CherryPy has built-in SSL support as of 3.0.0beta. See the `ssl_*` properties at http://www.cherrypy.org/wiki/ServerObject.
+      CherryPy has built-in SSL support as of 3.0.0beta. See the `ssl_*`
+      properties of :mod:`_cpserver`.
 
-      Earlier versions do not have built-in SSL support, but Tim Evans has written a module called [http://tools.cherrypy.org/wiki/SSLWithM2Crypto SslCherry] that uses M2Crypto for https support.  It's not quite ready for production use, but it looks promising.
+      Earlier versions do not have built-in SSL support, but Tim Evans has
+      written a module called `SslCherry <http://tools.cherrypy.org/wiki/SSLWithM2Crypto>`_
+      that uses M2Crypto for https support.  It's not quite ready for production
+      use, but it looks promising.
 
   * Does CherryPy prevent cross-site scripting ?
-      See [http://www.cert.org/advisories/CA-2000-02.html Malicious HTML Tags Embedded in Client Web Requests] and [http://www.cert.org/tech_tips/malicious_code_mitigation.html Understanding Malicious Content Mitigation for Web Developers] at [http://www.cert.org/ CERT] for an overview of Cross-Site Scripting (XSS) issues. It is ultimately up to the developer to remove potential XSS vulnerabilities from their apps and sites. 
+      See `Malicious HTML Tags Embedded in Client Web Requests <http://www.cert.org/advisories/CA-2000-02.html>`_
+      and `Understanding Malicious Content Mitigation for Web Developers <http://www.cert.org/tech_tips/malicious_code_mitigation.html>`_
+      at `CERT <http://www.cert.org/>`_ for an overview of Cross-Site Scripting
+      (XSS) issues. It is ultimately up to the developer to remove potential XSS
+      vulnerabilities from their apps and sites.
 
 Development Questions
 =====================
       Please see the FileUpload page for examples.
 
   * Can I perform HTTP based authentication (.htaccess)?
-      There are two filters implementing RFC 2617 : [wiki:DigestAuthFilter DigestAuthFilter] and [wiki:BasicAuthFilter BasicAuthFilter]
+      There are two filters implementing :rfc:`2617`: :doc:`authdigest` and :doc:`authbasic`.
 
   * What templating systems does CherryPy support? 
-      All of them! One of the core idea of CherryPy is to be templating language independent. It is important to us to let developers keep their habits and preferred tools. Hence CherryPy does not favor any templating language. But for some ideas, see [wiki:ChoosingATemplatingLanguage] and the [http://tools.cherrypy.org/wiki/ Tools] site.
+      All of them! One of the core idea of CherryPy is to be templating
+      language independent. It is important to us to let developers keep
+      their habits and preferred tools. Hence CherryPy does not favor any
+      templating language. But for some ideas, see
+      :doc:`/progguide/choosingtemplate` and the
+      `Tools wiki <http://tools.cherrypy.org/wiki/>`_.
 
-  * My default handler throws an exception complaining about the number of arguments. How to handle this? (I assume cherrypy 2.0b here)
+  * My default handler throws an exception complaining about the number of
+    arguments. How to handle this? (I assume cherrypy 2.0b here)
+
       Suppose you have the following handler class setup: ::
-
-        #!python
+        
         class Root:
             def project(self, id):
                 data = db.query("project", id)
 
       You can catch this by appending ``*args``, ``**kwargs`` to the default() method's parameter list. This way, the values 456 and 789 in the example will be placed in the 'args' list and the 'kwargs' dictionary will contain the string 'blah' for the key 'x'. In the following example, we just ignore any extra params: ::
 
-        #!python
         class Root:
             def project(self, id, *args, **kwargs):
                 data = db.query("project", id)
   * How do I publish objects with reserved Python names?
       Example ::
   
-        #!python
         class SomeClass(object):
             def __init__(self):
                 setattr(self,'print',self._print)
 
      (From cherrypy-users, an email by Remco Boerma)
 
-  * How does CherryPy compare to projects like mod_python, Twisted, and Nevow?
-      mod_python requires you to be running [http://httpd.apache.org/ Apache]. See http://www.modpython.org for more info. Since CherryPy 2.1, you can use mod_python as an interface to bridge CherryPy and Apache.
+  * How does CherryPy compare to projects like mod_python, Twisted, and Django?
+      mod_python requires you to be running `Apache <http://httpd.apache.org/>`_.
+      See http://www.modpython.org for more info. Since CherryPy 2.1, you can
+      use mod_python as an interface to bridge CherryPy and Apache.
 
-      Twisted is, well, twisted. You really have to spend the time to understand how the twisted framework works. It is deep and very powerful, but has a steep learning curve. CherryPy is, arguably, simpler to understand, due to its more traditional approach. Part of this comes from it not trying to do all the things that twisted does (SMTP, IRC, NNTP, etc etc). See http://twistedmatrix.com for more info.
+      Twisted is, well, twisted. You really have to spend the time to understand
+      how the twisted framework works. It is deep and very powerful, but has a
+      steep learning curve. CherryPy is, arguably, simpler to understand, due to
+      its more traditional approach. Part of this comes from it not trying to do
+      all the things that twisted does (SMTP, IRC, NNTP, etc etc). See
+      http://twistedmatrix.com for more info.
 
-      See [http://nevow.com/ Nevow's site] for more info. (Anyone have any experience with Nevow so we can have a better comparison with CherryPy?)
+      For a 3rd party discussion, refer to the
+      `PyWebOff blog <http://pyre.third-bit.com/pyweb/index.html>`_ which concluded:
+      
+         *"In no time at all, I was finished the library program. It took me
+         significantly less time than it did with either of Quixote or Webware,
+         and I'm very happy with the code that was produced. CherryPy needs more
+         documenting, but otherwise it gets two enthusiastic thumbs up."*
 
-      For a 3rd party discussion, refer to the [http://pyre.third-bit.com/pyweb/index.html PyWebOff blog] which concluded:
+  * When you run cherrypy and two dudes browse your website at the same time,
+    does cherrypy create two instances of your root object? How does that work?
+    I don't get it.
 
-        ''"In no time at all, I was finished the library program. It took me significantly less time than it did with either of Quixote or Webware, and I'm very happy with the code that was produced. CherryPy needs more documenting, but otherwise it gets two enthusiastic thumbs up."''
-
-  * When you run cherrypy and two dudes browse your website at the same time, does cherrypy create two instances of your root object? How does that work? I don't get it.
-      No, just one instance. It's no different than having two threads in any other Python application call the same method at the same time: each thread has its own set of local variables so they don't stomp each other.
+      No, just one instance. It's no different than having two threads in any
+      other Python application call the same method at the same time: each
+      thread has its own set of local variables so they don't stomp each other.
 
   * How do I get CherryPy to work if I don't have root?
-      Just append it to the path.  Put the following at the top of the files you need CherryPy for: ::
+      Just append it to the path.  Put the following at the top of the files
+      you need CherryPy for: ::
 
-        #!python
         import sys
         sys.path.append("your local dir path")
 

sphinx/source/progguide/choosingtemplate.rst

+.. _ChoosingATemplatingLanguage:
+
+******************************
+Choosing a templating language
+******************************
+
+CherryPy is an open-ended Web framework that integrates with a wide variety of templating systems. This document is to help you choose which one is right for you.
+
+Cheetah
+=======
+
+.. tabularcolumns:: |l|c|l|
+
+================= ================ ================
+Feature           Supported        Comment
+================= ================ ================
+Caching           [X]              You can compile templates into python classes.
+Speed             moderate         Not a speed demon. But critical part of the library (the namemapper) is also available as binary for linux, windows and makes for great performance improvement
+Wysiwyg           [ ]              No. Use any text editor  
+Flexibility       Great
+Pythonic design   [X]              Very much so, it can use python constructs in the template
+Pure python       Yes
+XML Syntax        [ ]              Thank heavens no!
+Language elements                  See the `Cheetah <http://www.cheetahtemplate.org/>`_ docs
+Learning curve    very short
+Community         Large
+Summary:                           Cheetah is one of the simplest and most comprehensive templating engines you'll find. Excellent documentation.
+================= ================ ================
+
+
+
+ClearSilver
+===========
+
+====================  ============  ==================
+Feature               Supported     Comment
+====================  ============  ==================
+Caching               [ ]           
+Speed                               ''Untested, we don't have a benchmark yet''     
+Wysiwyg               [ ]           No. Use any text editor     
+Targets               All       
+Flexibility           Great           
+Pythonic design       []            Written in c, includes drivers for python, ruby, perl, and java     
+CherryPy Integration  []           
+Pure python           No           
+XML Syntax            [X]           
+Language elements                   See the `ClearSilver <http://www.clearsilver.net/docs/>`_ docs     
+Learning curve        short           
+Community             Small           
+i18n                  [ ]           
+Summary:                            ClearSilver uses a dataset driven approach which completely separates layout and application logic.     
+====================  ============  ==================
+
+`Genshi <http://genshi.edgewall.org>`_
+=======================================
+
+See the `Genshi tutorial <http://tools.cherrypy.org/wiki/Genshi>`_.
+
+==================== =============== ==================
+Feature              Supported       Comment    
+==================== =============== ==================
+Caching              [X]             
+Speed                                `Genshi performance <http://genshi.edgewall.org/wiki/GenshiPerformance>`_
+WYSIWYG              [X]             If you're using a XHTML Compliant WYSIWYG editor.
+Targets              XML or Text     Only used for outputting structured text files or XML based files such as XHTML 
+Flexibility          Great           
+Pythonic design      [X]          
+CherryPy Integration [X]             `Genshi Tutorial with CherryPy <http://genshi.edgewall.org/wiki/GenshiTutorial>`_
+Pure python          [X]           
+XML Syntax           [X]             XHTML + additional namespaces     
+Language elements                    XHTML + additional tags and inline Python.  See `Genshi's Documentation <http://genshi.edgewall.org/wiki/Documentation/index.html>`_.
+Learning curve       short           Do you know XHTML?  Then you're 75% of the way there!
+Community            Growing         Trac and `TurboGears <http://www.turbogears.org/>`_ (via `ToscaWidgets <http://toscawidgets.org/>`_) are both moving to Genshi.
+i18n                 [X]             
+Summary:                             Plain XHTML templates make Genshi easy to use even for web designers who don't know Python.  Its considered by many to be the successor to Kid.
+==================== =============== ==================
+
+Kid
+===
+
+HTMLTemplate
+============
+
+Nevow
+=====
+
+PSP
+===
+
+PyMeld
+======
+
+===================== ========== ===============
+Feature               Supported  Comment       
+===================== ========== ===============
+Caching               [ ]        Left to the user.      
+Speed                            ''Untested, we don't have a benchmark yet''     
+Wysiwyg               [X]        Templates are pure HTML/XHTML and can contain dummy content     
+Targets               All       
+Flexibility                      HTML-ish markup only. No other formats.           
+Pythonic design       [X]        Very.     
+CherryPy Integration  [ ]           
+Pure python           Yes           
+XML Syntax            [ ]        Not really. Relies on "id" attributes in HTML/XHTML.     
+Language elements                See the `PyMeld docs <http://www.entrian.com/PyMeld/>`_     
+Learning curve                   Gentle and short            
+Community                        `None <http://www.google.com/search?q=%22pymeld+users%22>`_           
+i18n                  [ ]        Left to user      
+Summary:                         Elegant and unique tool for manipulating HTML in a Pythonic way. Any (X)HTML element with an "id" attribute can be manipulated -- including cloning, deletion, or attribute changing.     
+===================== ========== ===============
+
+
+XSLT
+====
+
+===================== ============== =====================
+Feature               Supported      Comment       
+===================== ============== =====================
+Caching               [ ]            None but the Picket filter has a basic cache.      
+Speed                                ''Untested, we don't have a benchmark yet''     
+Wysiwyg               [ ]            No. Use any text editor or specific XSL editor     
+Targets               All       
+Flexibility           Great           
+Pythonic design       [ ]            It's totally language/platform independent     
+CherryPy Integration  [X]            [wiki:Picket Picket] is a filter implementation using the `4Suite <http://4suite.org>`_ framework     
+Pure python           No           
+XML Syntax            [X]           
+Language elements                    See the `XSLT <http://www.w3.org/TR/xslt>`_ doc     
+Learning curve        Depends on you XSLT is quite a big beast but you will find plenty of documentation      
+Community             Big           
+i18n                  [X]           
+Summary:                             It's a standard. XSLT is fantastic if you are mainly using XML documents. It's also totally language and platform independent and therefore you will not have to learn a new templating language if you change your programming language.    
+===================== ============== =====================
+
+Xyaptu
+======
+
+===================== ============== =====================
+Feature               Supported      Comment       
+===================== ============== =====================
+Caching               [ ]            Only if there is a !DoneByMyselfImplementation. - xyaptu is a templating unit, nothing more..      
+Speed                                ''Untested, we don't have a benchmark yet''     
+Wysiwyg               [ ]            Nope: Nano, vim, emacs, notepad.... but by using xmlstyle tags, the language is designed not to interfere with graphical design software (as long as this software will also leave in unknown tags that is)    
+Targets               anything       Whether it be javascript, xml, html, python, csv or whatever you want. 
+Flexibility           no complaints  Loops, conditions, not target language dependent     
+Pythonic design       [X]            Using dictionaries, tuples, strings and generators     
+CherryPy Integration  [X]            There is a filter built on top of CherryPy, including samples etc     
+Pure python           [X]            all the way. 3 modules: the Filter, Xyaptu and Yaptu - works everywhere     
+Language elements     7              See the XyaptuFilter, subsection Markup-syntax     
+Learning curve        curve?         Hardly any. The filter might be the toughest part (say, 5 minutes?)      
+Community             Tiny           Too bad, but it's the truth     
+i18n                  [X]            not using the i18n module though. Xyaptu is based on Document Name Spaces, this is a regular dictionary. The keys are in your template, and will be replaced with the values in this dictionary. So having multiple dictionaries (one for each language) is enough.. It's not perfect, but at least it's something usefull :)      
+Summary:                             see: XyaptuFilter [[br]] Xyaptu stands for: eXtended  Yet Another Python Templating Unit    
+===================== ============== =====================
+
+ZPT
+===
+
+===================== ============== =====================
+Feature               Supported      Comment       
+===================== ============== =====================
+Caching               [ ]            ''Unknown''          
+Speed                 [ ]          
+WYSIWYG               [ ]            XHTML can be edited in a WYSIWYG editor, with scripting is placed in an XML namespace for tags and attributes     
+Targets               XML            Includes XHTML and other XML formats (SVG, MathML, etc.)    
+Pythonic design       [ ]          
+Flexibility               
+CherryPy Integration               
+Pure Python           [X]          
+ XML Syntax           [X]           
+Language Elements                    See `ZPT Documentation <http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/AppendixC.stx>`_     
+Learning Curve        Medium         Learning curve depends on knowledge of Python and XML    
+Community             Medium         `Zope <http://www.zope.org/>`_ depends on ZPT, so community support is readily available.     
+i18n                  Unknown        i18n features are available in the Zope framework, but may not work outside of Zope.     
+Summary                              Zope Page Templates are relatively easy for web designers to edit without disturbing scripting already embedded in the page. The basic syntax tends to be clean and simple, while more complex tasks are possible. However, ZPT can only be used with XML documents, not other text-based documents such as CSS or JavaScript.     
+===================== ============== =====================
+
+py.xml
+======
+
+===================== ============== =====================
+Feature               Supported      Comment       
+===================== ============== =====================
+Caching               [ ]            ''None''          
+Speed                 [ ]          
+WYSIWYG               [ ]            No. Use any text editor     
+Targets               XML            Includes XHTML and other XML formats (SVG, MathML, etc.)    
+Pythonic design       [X]            py.xml is designed to be a Python to generating XML     
+Flexibility               
+CherryPy Integration               
+Pure Python           [X]          
+ XML Syntax           [ ]            No. All code is generated with Python calls     
+Language Elements               
+Learning Curve        None           If you can do Python you can do py.xml     
+Community             Unknown           
+i18n                  None           You will have to provide i18n yourself     
+Summary                              The py lib offers a pythonic way to generate xml/html, based on ideas from xist which uses python class objects to build xml trees. However, xist's implementation is somewhat heavy because it has additional goals like transformations and supporting many namespaces. But its basic idea is very easy.     
+===================== ============== =====================
+
+Old/Unmaintained
+================
+
+CherryTemplate
+--------------
+
+See http://cherrytemplate.python-hosting.com/

sphinx/source/progguide/exceptions.rst

 *********************
 
 
-`CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ provides (and uses) exceptions for declaring that the HTTP response should be a status other than the default "200 OK". You can ``raise`` them like normal Python exceptions. You can also call them and they will raise themselves; this means you can set an :class:`HTTPError <cherrypy.HTTPError>` or :class:`HTTPRedirect <cherrypy.HTTPRedirect>` as the ``request.handler``.
+CherryPy provides (and uses) exceptions for declaring that the HTTP response
+should be a status other than the default "200 OK". You can ``raise`` them like
+normal Python exceptions. You can also call them and they will raise themselves;
+this means you can set an :class:`HTTPError` or :class:`HTTPRedirect` as the
+``request.handler``.
 
 HTTPError
-=======================================
+=========
 
-This exception can be used to automatically send a response using a http status code, with an appropriate error page. :class:`HTTPError <cherrypy.HTTPError>` takes an optional ``status`` argument (which must be between 400 and 599); it defaults to 500 ("Internal Server Error"). It also takes an optional ``message`` argument, which will be returned in the response body. See `this page <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4 RFC 2616>`_ for a complete list of available error codes and when to use them.
+This exception can be used to automatically send a response using a http status
+code, with an appropriate error page. :class:`HTTPError` takes an optional
+``status`` argument (which must be between 400 and 599); it defaults to 500
+("Internal Server Error"). It also takes an optional ``message`` argument,
+which will be returned in the response body. See
+`this page <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4 RFC 2616>`_
+for a complete list of available error codes and when to use them.
 
 Examples::
 
-
-	#!python
-	raise cherrypy.HTTPError(403)
-	raise cherrypy.HTTPError("403 Forbidden", "You are not allowed to access this resource.")
+    raise cherrypy.HTTPError(403)
+    raise cherrypy.HTTPError("403 Forbidden", "You are not allowed to access this resource.")
 
 
 NotFound
--------------------------------------
+--------
 
-This exception is raised when `CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ is unable to map a requested path to an internal method. It's equivalent to raising :class:`HTTPError("404 Not Found") <cherrypy.HTTPError>`.
+This exception is raised when CherryPy is unable to map a requested path to an
+internal method. It's equivalent to raising
+:class:`HTTPError("404 Not Found") <cherrypy.HTTPError>`.
 
 HTTPRedirect
-=============================================
+============
 
 This exception will force a HTTP redirect to the URL or URL's you give it.
 
-There are multiple types of redirect, from which you can select via the ``status`` argument. If you do not provide a ``status`` arg, it defaults to 303 (or 302 if responding with HTTP/1.0).
+There are multiple types of redirect, from which you can select via the
+``status`` argument. If you do not provide a ``status`` arg, it defaults to 303
+(or 302 if responding with HTTP/1.0).
 
 Examples::
 
-
-	#!python
-	raise cherrypy.HTTPRedirect("")
-	raise cherrypy.HTTPRedirect("/abs/path", 307)
-	raise cherrypy.HTTPRedirect(["path1", "path2?a=1&b=2"], 301)
+    raise cherrypy.HTTPRedirect("")
+    raise cherrypy.HTTPRedirect("/abs/path", 307)
+    raise cherrypy.HTTPRedirect(["path1", "path2?a=1&b=2"], 301)
 
 
 Redirecting POST
 ----------------
 
-When you GET a resource and are redirected by the server to another Location, there's generally no problem since GET is both a "safe method" (there should be no side-effects) and an "idempotent method" (multiple calls are no different than a single call). POST, however, is neither safe nor idempotent--if you charge a credit card, you don't want to be charged twice by a redirect!
+When you GET a resource and are redirected by the server to another Location,
+there's generally no problem since GET is both a "safe method" (there should
+be no side-effects) and an "idempotent method" (multiple calls are no different
+than a single call). POST, however, is neither safe nor idempotent--if you
+charge a credit card, you don't want to be charged twice by a redirect!
 
-For this reason, ''none'' of the 3xx responses permit a user-agent (browser) to resubmit a POST on redirection without first confirming the action with the user:
+For this reason, *none* of the 3xx responses permit a user-agent (browser) to
+resubmit a POST on redirection without first confirming the action with the user:
 
 
 
-=====	=================================	===========
-300	Multiple Choices			Confirm with the user
-301	Moved Permanently			Confirm with the user
-302	Found (Object moved temporarily)	Confirm with the user
-303	See Other				GET the new URI--no confirmation
-304	Not modified				(for conditional GET only--POST should not raise this error)
-305	Use Proxy				Confirm with the user
-307	Temporary Redirect			Confirm with the user
-=====	=================================	===========
+=====    =================================    ===========
+300      Multiple Choices                     Confirm with the user
+301      Moved Permanently                    Confirm with the user
+302      Found (Object moved temporarily)     Confirm with the user
+303      See Other                            GET the new URI--no confirmation
+304      Not modified                         (for conditional GET only--POST should not raise this error)
+305      Use Proxy                            Confirm with the user
+307      Temporary Redirect                   Confirm with the user
+=====    =================================    ===========
 
-However, browsers have historically implemented these restrictions poorly; in particular, many browsers do not force the user to confirm 301, 302 or 307 when redirecting POST. For this reason, `CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ defaults to :class:`HTTPRedirect(303) <cherrypy.HTTPRedirect>`, which most user-agents appear to have implemented correctly. Therefore, if you raise :class:`HTTPRedirect(new_uri) <cherrypy.HTTPRedirect>` for a POST request, the user-agent will most likely attempt to GET the new URI (without asking for confirmation from the user). We realize this is confusing for developers; but it's the safest thing we could do. You are of course free to raise :class:`HTTPRedirect(uri, status=302) <cherrypy.HTTPRedirect>` or any other 3xx status if you know what you're doing, but given the environment, we couldn't let any of those be the default.
+However, browsers have historically implemented these restrictions poorly;
+in particular, many browsers do not force the user to confirm 301, 302 or 307
+when redirecting POST. For this reason, CherryPy defaults to
+:class:`HTTPRedirect(303) <cherrypy.HTTPRedirect>`, which most user-agents
+appear to have implemented correctly. Therefore, if you raise
+:class:`HTTPRedirect(new_uri) <cherrypy.HTTPRedirect>` for a POST request,
+the user-agent will most likely attempt to GET the new URI (without asking for
+confirmation from the user). We realize this is confusing for developers;
+but it's the safest thing we could do. You are of course free to raise
+:class:`HTTPRedirect(uri, status=302) <cherrypy.HTTPRedirect>` or any other
+3xx status if you know what you're doing, but given the environment, we
+couldn't let any of those be the default.
 
 InternalRedirect
 ----------------
 
-This exception will redirect processing to another path within the site (without informing the client). Provide the new path as an argument when raising the exception. Provide any params in the querystring for the new URL.
+This exception will redirect processing to another path within the site
+(without informing the client). Provide the new path as an argument when
+raising the exception. Provide any params in the querystring for the new URL.
 
 *********************
 Custom Error Handling
 Anticipated HTTP responses
 ==========================
 
-The 'error_page' config namespace can be used to provide custom HTML output for expected responses (like 404 Not Found). Supply a filename from which the output will be read. The contents will be interpolated with the values %(status)s, %(message)s, %(traceback)s, and %(version)s using plain old Python `string formatting <http://docs.python.org/library/stdtypes.html#string-formatting-operations>`_.
+The 'error_page' config namespace can be used to provide custom HTML output for
+expected responses (like 404 Not Found). Supply a filename from which the output
+will be read. The contents will be interpolated with the values %(status)s,
+%(message)s, %(traceback)s, and %(version)s using plain old Python
+`string formatting <http://www.python.org/doc/2.6.4/library/stdtypes.html#string-formatting-operations>`_.
 
 ::
 
-	_cp_config = {'error_page.404': os.path.join(localDir, "static/index.html")}
+    _cp_config = {'error_page.404': os.path.join(localDir, "static/index.html")}
 
 
-Beginning in version 3.1, you may also provide a function or other callable as an error_page entry. It will be passed the same status, message, traceback and version arguments that are interpolated into templates::
+Beginning in version 3.1, you may also provide a function or other callable as
+an error_page entry. It will be passed the same status, message, traceback and
+version arguments that are interpolated into templates::
 
+    def error_page_402(status, message, traceback, version):
+        return "Error %s - Well, I'm very sorry but you haven't paid!" % status
+    cherrypy.config.update({'error_page.402': error_page_402})
 
-	#!python
-	def error_page_402(status, message, traceback, version):
-	    return "Error %s - Well, I'm very sorry but you haven't paid!" % status
-	cherrypy.config.update({'error_page.402': error_page_402})
-
-
-Also in 3.1, in addition to the numbered error codes, you may also supply "error_page.default" to handle all codes which do not have their own error_page entry.
+Also in 3.1, in addition to the numbered error codes, you may also supply
+"error_page.default" to handle all codes which do not have their own error_page entry.
 
 
 
 Unanticipated errors
 ====================
 
-`CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ also has a generic error handling mechanism: whenever an unanticipated error occurs in your code, it will call ``request.error_response`` to set the response status, headers, and body. By default, this is the same output as :class:`HTTPError(500) <cherrypy.HTTPError>`. If you want to provide some other behavior, you generally replace "request.error_response".
+CherryPy also has a generic error handling mechanism: whenever an unanticipated
+error occurs in your code, it will call :func:`Request.error_response` to set
+the response status, headers, and body. By default, this is the same output as
+:class:`HTTPError(500) <cherrypy.HTTPError>`. If you want to provide some other
+behavior, you generally replace "request.error_response".
 
-Here is some sample code that shows how to display a custom error message and send an e-mail containing the error::
+Here is some sample code that shows how to display a custom error message and
+send an e-mail containing the error::
 
+    from cherrypy import _cperror
 
-	#!python
-	from cherrypy import _cperror
+    def handle_error():
+        cherrypy.response.status = 500
+        cherrypy.response.body = ["<html><body>Sorry, an error occured</body></html>"]
+        sendMail('error@domain.com', 'Error in your web app', _cperror.format_exc())
 
-	def handle_error():
-	    cherrypy.response.status = 500
-	    cherrypy.response.body = ["<html><body>Sorry, an error occured</body></html>"]
-	    sendMail('error@domain.com', 'Error in your web app', _cperror.format_exc())
+    class Root:
+        _cp_config = {'request.error_response': handle_error}
 
-	class Root:
-	    _cp_config = {'request.error_response': handle_error}
 
+Note that you have to explicitly set :attr:`response.body <cherrypy._cprequest.Response.body>`
+and not simply return an error message as a result.
 
-Note that you have to explicitly set ``cherrypy.response.body`` and not simply return an error message as a result.
-
-

sphinx/source/progguide/sessions.rst

 Expiring Sessions
 =================
 
-You can force a session to expire with the ``cherrypy.lib.sessions.expire`` function.  Simply call that function at the point you want the session to expire, and it will cause the session cookie to expire client-side.
+You can force a session to expire with :func:`cherrypy.lib.sessions.expire`.  Simply call that function at the point you want the session to expire, and it will cause the session cookie to expire client-side.
 
 ===========================
 Session Fixation Protection
 ===========================
 
-If `CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ receives, via a request cookie, a session id that it does not recognize, it will reject that id and create a new one to return in the response cookie. This `helps prevent session fixation attacks <http://en.wikipedia.org/wiki/Session_fixation#Regenerate_SID_on_each_request>`_. However, `CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ "recognizes" a session id by looking up the saved session data for that id. Therefore, if you never save any session data, **you will get a new session id for every request**.
+If CherryPy receives, via a request cookie, a session id that it does not recognize, it will reject that id and create a new one to return in the response cookie. This `helps prevent session fixation attacks <http://en.wikipedia.org/wiki/Session_fixation#Regenerate_SID_on_each_request>`_. However, CherryPy "recognizes" a session id by looking up the saved session data for that id. Therefore, if you never save any session data, **you will get a new session id for every request**.
 
 ================
 Sharing Sessions
 ================
 
-If you run multiple instances of `CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ (for example via mod_python behind Apache prefork), you most likely cannot use the RAM session backend, since each instance of `CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ will have its own memory space. Use a different backend instead, and verify that all instances are pointing at the same file or db location. Alternately, you might try a load balancer which makes sessions "sticky". Google is your friend, there.
+If you run multiple instances of CherryPy (for example via mod_python behind Apache prefork), you most likely cannot use the RAM session backend, since each instance of CherryPy will have its own memory space. Use a different backend instead, and verify that all instances are pointing at the same file or db location. Alternately, you might try a load balancer which makes sessions "sticky". Google is your friend, there.
 
 ================
 Expiration Dates
 
 The response cookie will possess an expiration date to inform the client at which point to stop sending the cookie back in requests. If the server time and client time differ, expect sessions to be unreliable. **Make sure the system time of your server is accurate**.
 
-`CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ defaults to a 60-minute session timeout, which also applies to the cookie which is sent to the client. Unfortunately, some versions of Safari ("4 public beta" on Windows XP at least) appear to have a bug in their parsing of the GMT expiration date--they appear to interpret the date as one hour in the past. Sixty minutes minus one hour is pretty close to zero, so you may experience this bug as a new session id for every request, unless the requests are less than one second apart. To fix, try increasing the session.timeout.
+CherryPy defaults to a 60-minute session timeout, which also applies to the cookie which is sent to the client. Unfortunately, some versions of Safari ("4 public beta" on Windows XP at least) appear to have a bug in their parsing of the GMT expiration date--they appear to interpret the date as one hour in the past. Sixty minutes minus one hour is pretty close to zero, so you may experience this bug as a new session id for every request, unless the requests are less than one second apart. To fix, try increasing the session.timeout.
 
 On the other extreme, some users report Firefox sending cookies after their expiration date, although this was on a system with an inaccurate system time. Maybe FF doesn't trust system time.