Changeset 60:6ae681d2adcf in livinglogic.python.nightshade

Show
Ignore:
Timestamp:
01/06/08 22:36:59 (12 years ago)
Author:
Walter Doerwald <walter@…>
Branch:
default
Message:

Update to new names of doc elements. Added ReST documents.

Files:
3 added
5 modified
1 moved

Legend:

Unmodified
Added
Removed
  • INSTALL.xml

    r46 r60  
    11<?xml version='1.0' encoding='iso-8859-1'?> 
    2 <section><title>Requirements</title> 
    3 <par>To use this module you need the following software packages:</par> 
    4 <olist> 
    5 <item><link href="http://www.python.org/">Python 2.5</link>;</item> 
    6 <item><pyref module="ll">ll-core</pyref> (at least 1.8);</item> 
    7 <item><pyref module="ll">ll-orasql</pyref> (at least 1.17.3; 
    8 which in turn requires <link href="http://www.computronix.com/utilities.shtml#Oracle"><app>cx_Oracle</app></link>).</item> 
    9 <item><link href="http://www.cherrypy.org"><app>CherryPy</app></link>.</item> 
    10 </olist> 
     2<section><h>Requirements</h> 
     3<p>To use this module you need the following software packages:</p> 
     4<ol> 
     5<li><a href="http://www.python.org/">Python 2.5</a>;</li> 
     6<li><pyref module="ll">ll-core</pyref> (at least 1.8);</li> 
     7<li><pyref module="ll">ll-orasql</pyref> (at least 1.17.3; 
     8which in turn requires <a href="http://www.python.net/crew/atuining/cx_Oracle/"><app>cx_Oracle</app></a>).</li> 
     9<li><a href="http://www.cherrypy.org"><app>CherryPy</app></a>.</li> 
     10</ol> 
    1111</section> 
    1212 
    13 <section><title>Installation</title> 
    14 <par><app moreinfo="http://peak.telecommunity.com/DevCenter/setuptools">setuptools</app> 
    15 is used for installation so you can install this module with the following command:</par> 
     13<section><h>Installation</h> 
     14<p><app moreinfo="http://peak.telecommunity.com/DevCenter/setuptools">setuptools</app> 
     15is used for installation so you can install this module with the following command:</p> 
    1616 
    1717<prog> 
     
    1919</prog> 
    2020 
    21 <par>If you want to install from source, you can download one of the 
    22 <link href="root:nightshade/Download.html">distribution archives</link>, unpack it, 
    23 enter the directory and execute the following command:</par> 
     21<p>If you want to install from source, you can download one of the 
     22<a href="root:nightshade/Download.html">distribution archives</a>, unpack it, 
     23enter the directory and execute the following command:</p> 
    2424<prog> 
    2525python setup.py install 
    2626</prog> 
    2727 
    28 <par>This will install <module>ll.nightshade</module> as part of the <module>ll</module> 
    29 package.</par> 
     28<p>This will install <mod>ll.nightshade</mod> as part of the <mod>ll</mod> 
     29package.</p> 
    3030 
    31 <par>For Windows a binary distribution is provided. To install it, 
    32 double click it, and follow the instructions.</par> 
     31<p>For Windows a binary distribution is provided. To install it, 
     32double click it, and follow the instructions.</p> 
    3333 
    34 <par>If you have difficulties installing this software, send a problem report 
    35 to Walter Dörwald (<email>walter@livinglogic.de</email>).</par> 
     34<p>If you have difficulties installing this software, send a problem report 
     35to Walter Dörwald (<email>walter@livinglogic.de</email>).</p> 
    3636</section> 
  • MANIFEST.in

    r47 r60  
    1 include NEWS 
     1include README.rst 
     2include NEWS.rst 
    23include NEWS.xml 
    3 include INSTALL 
     4include INSTALL.rst 
    45include INSTALL.xml 
    5 include MIGRATION 
     6include MIGRATION.rst 
    67include MIGRATION.xml 
    7 include README 
    88include Makefile 
  • MIGRATION.xml

    r55 r60  
    11<?xml version='1.0' encoding='iso-8859-1'?> 
    2 <section><title>Migrating to version 0.10</title> 
     2<section><h>Migrating to version 0.10</h> 
    33 
    4 <par>When a <class>Connect</class> object is used as a decorator the 
     4<p>When a <class>Connect</class> object is used as a decorator the 
    55database connection is no longer passed to the decorated function. You have to 
    66store the <class>Connect</class> object somewhere and call it's new 
    7 <method>cursor</method> explicitely.</par> 
     7<meth>cursor</meth> method explicitely.</p> 
    88 
    99</section> 
    1010 
    1111 
    12 <section><title>Migrating to version 0.8</title> 
     12<section><h>Migrating to version 0.8</h> 
    1313 
    14 <par>The class <class>withconnection</class> has been renamed to 
    15 <class>Connect</class>.</par> 
     14<p>The class <class>withconnection</class> has been renamed to 
     15<class>Connect</class>.</p> 
    1616 
    17 <par>Calling functions and procedures has changed a bit. Replace the following 
    18 old code:</par> 
     17<p>Calling functions and procedures has changed a bit. Replace the following 
     18old code:</p> 
    1919 
    2020<prog> 
     
    2626</prog> 
    2727 
    28 <par>with</par> 
     28<p>with</p> 
    2929 
    3030<prog> 
  • NEWS.xml

    r58 r60  
    1 <section><title>Changes in 0.10 (released 09/04/2007)</title> 
    2 <ulist> 
    3 <item>When a <class>Connect</class> object is used as a decorator the 
     1<section><h>Changes in 0.10 (released 09/04/2007)</h> 
     2<ul> 
     3<li>When a <class>Connect</class> object is used as a decorator the 
    44database connection is no longer passed to the decorated function. This means 
    55that there will no longer be any signature mismatch between the original 
    66function and the decorated function. However the <class>Connect</class> object 
    7 must be stored somewhere else and the user must call the new <method>cursor</method> 
    8 method to get a cursor.</item> 
     7must be stored somewhere else and the user must call the new <meth>cursor</meth> 
     8method to get a cursor.</li> 
    99 
    10 <item>Keyword argument in the <class>Connect</class> constructor are passed 
    11 on the the <function>connect</function> call.</item> 
    12 </ulist> 
     10<li>Keyword argument in the <class>Connect</class> constructor are passed 
     11on the the <func>connect</func> call.</li> 
     12</ul> 
    1313</section> 
    1414 
    1515 
    16 <section><title>Changes in 0.9 (released 07/18/2007)</title> 
    17 <ulist> 
    18 <item>Added support for the <lit>Cache-Control</lit> header.</item> 
    19 </ulist> 
     16<section><h>Changes in 0.9 (released 07/18/2007)</h> 
     17<ul> 
     18<li>Added support for the <lit>Cache-Control</lit> header.</li> 
     19</ul> 
    2020</section> 
    2121 
    2222 
    23 <section><title>Changes in 0.8.1 (released 06/26/2007)</title> 
    24 <ulist> 
    25 <item>Fixed a bug in <method>Call.__call__</method> (calling the procedure 
    26 wasn't retried after the connection got lost).</item> 
    27 </ulist> 
     23<section><h>Changes in 0.8.1 (released 06/26/2007)</h> 
     24<ul> 
     25<li>Fixed a bug in <meth>Call.__call__</meth> (calling the procedure 
     26wasn't retried after the connection got lost).</li> 
     27</ul> 
    2828</section> 
    2929 
    3030 
    31 <section><title>Changes in 0.8 (released 06/21/2007)</title> 
    32 <ulist> 
    33 <item><class>withconnection</class> has been renamed to <class>Connect</class> 
    34 and the implementation of <method>__call__</method> has been fixed.</item> 
    35 <item><class>Call</class> now needs a <class>Connect</class> object as the second 
     31<section><h>Changes in 0.8 (released 06/21/2007)</h> 
     32<ul> 
     33<li><class>withconnection</class> has been renamed to <class>Connect</class> 
     34and the implementation of <meth>__call__</meth> has been fixed.</li> 
     35<li><class>Call</class> now needs a <class>Connect</class> object as the second 
    3636argument in the constructor (instead of taking <arg>connectstring</arg>, 
    37 <arg>pool</arg> and <arg>retry</arg> arguments).</item> 
    38 </ulist> 
     37<arg>pool</arg> and <arg>retry</arg> arguments).</li> 
     38</ul> 
    3939</section> 
    4040 
    4141 
    42 <section><title>Changes in 0.7.1 (released 05/12/2007)</title> 
    43 <ulist> 
    44 <item>Fixed a bug that surfaced after the connection to the database 
    45 was lost.</item> 
    46 </ulist> 
     42<section><h>Changes in 0.7.1 (released 05/12/2007)</h> 
     43<ul> 
     44<li>Fixed a bug that surfaced after the connection to the database 
     45was lost.</li> 
     46</ul> 
    4747</section> 
    4848 
    4949 
    50 <section><title>Changes in 0.7 (released 03/16/2007)</title> 
    51 <ulist> 
    52 <item>A new decorator <class>withconnection</class> has been added. This 
    53 can be use to retry database operations in case of stale connections.</item> 
    54 </ulist> 
     50<section><h>Changes in 0.7 (released 03/16/2007)</h> 
     51<ul> 
     52<li>A new decorator <class>withconnection</class> has been added. This 
     53can be use to retry database operations in case of stale connections.</li> 
     54</ul> 
    5555</section> 
    5656 
    5757 
    58 <section><title>Changes in 0.6 (released 03/12/2007)</title> 
    59 <ulist> 
    60 <item>Initial public release.</item> 
    61 </ulist> 
     58<section><h>Changes in 0.6 (released 03/12/2007)</h> 
     59<ul> 
     60<li>Initial public release.</li> 
     61</ul> 
    6262</section> 
  • README.rst

    r36 r60  
    11ll-nightshade 
     2============= 
    23 
    3 Serve the output of TOXIC functions/procedures with CherryPy 
     4Serve the output of TOXIC functions/procedures with CherryPy__. 
     5 
     6__ http://www.cherrypy.org/ 
    47 
    58For documentation read the source. 
    69 
    7 For requirements and installation instructions read INSTALL. 
     10For requirements and installation instructions read ``INSTALL.rst``. 
    811 
    9 For a list of new features and bugfixes read NEWS. 
     12For a list of new features and bugfixes read ``NEWS.rst``. 
    1013 
    11 For the license read nightshade.py. 
     14For the license read ``nightshade.py``. 
    1215 
    1316ll-nightshade is available from ftp://ftp.livinglogic.de/pub/livinglogic/nightshade/ 
  • src/ll/nightshade.py

    r55 r60  
    22 
    33""" 
    4 <par>This module provides a class <pyref class="Call"><class>Call</class></pyref> 
     4<p>This module provides a class <pyref class="Call"><class>Call</class></pyref> 
    55that allows you to use Oracle PL/SQL procedures/functions as 
    6 <link href="http://www.cherrypy.org/">CherryPy</link> response handlers. 
     6<a href="http://www.cherrypy.org/">CherryPy</a> response handlers. 
    77A <class>Call</class> objects wraps a <pyref module="ll.orasql" class="Procedure"><class>Procedure</class></pyref> 
    88or <pyref module="ll.orasql" class="Function"><class>Function</class></pyref> object 
    9 from  <pyref module="ll.orasql"><module>ll.orasql</module></pyref>.</par> 
    10 <par>For example, you might have the following PL/SQL function:</par> 
     9from  <pyref module="ll.orasql"><mod>ll.orasql</mod></pyref>.</p> 
     10<p>For example, you might have the following PL/SQL function:</p> 
    1111<prog><![CDATA[ 
    1212create or replace function helloworld 
     
    1717as 
    1818begin 
    19     return '<html><head><title>Hello ' || who || '</title></head><body><h1>Hello, ' || who || '!</h1></body></html>'; 
     19    return '<html><head><h>Hello ' || who || '</h></head><body><h1>Hello, ' || who || '!</h1></body></html>'; 
    2020end; 
    2121]]></prog> 
    22 <par>Using this function as a CherryPy response handler can be done like this:</par> 
     22<p>Using this function as a CherryPy response handler can be done like this:</p> 
    2323<prog> 
    2424import cherrypy 
     
    4242import cherrypy 
    4343 
    44 import cx_Oracle 
    45  
    4644from ll import orasql 
    4745 
     
    7775def httpdate(dt): 
    7876    """ 
    79     <par>Return a string suitable for a <z>Last-Modified</z> and <z>Expires</z> header.</par> 
     77    <p>Return a string suitable for a <z>Last-Modified</z> and <z>Expires</z> header.</p> 
    8078     
    81     <par><arg>dt</arg> is a <class>datetime.datetime</class> object. 
     79    <p><arg>dt</arg> is a <class>datetime.datetime</class> object. 
    8280    If <lit><arg>dt</arg>.tzinfo</lit> is <lit>None</lit> <arg>dt</arg> is assumed 
    8381    to be in the local timezone (using the current UTFC offset which might be 
    84     different from the one used by <arg>dt</arg>).</par> 
     82    different from the one used by <arg>dt</arg>).</p> 
    8583    """ 
    8684    if dt.tzinfo is None: 
     
    9391class cache(object): 
    9492    """ 
    95     <par>Decorator that adds caching to a CherryPy handler.</par> 
     93    <p>Decorator that adds caching to a CherryPy handler.</p> 
    9694     
    97     <par>Calling a <class>cache</class> object will cache return values 
     95    <p>Calling a <class>cache</class> object will cache return values 
    9896    of the decorated function for a certain amount of time. You can pass 
    9997    the timespan either via <arg>timedelta</arg> (which must be a 
     
    145143def conditional(func): 
    146144    """ 
    147     <par>Decorator that adds handling of conditional <lit>GET</lit>s to a CherryPy handler.</par> 
     145    <p>Decorator that adds handling of conditional <lit>GET</lit>s to a CherryPy handler.</p> 
    148146     
    149     <par>The decorated function will correctly handle the <lit>If-Modified-Since</lit> 
     147    <p>The decorated function will correctly handle the <lit>If-Modified-Since</lit> 
    150148    and <lit>If-None-Match</lit> request headers. For this to work properly 
    151149    the decorated function should set the <lit>Last-Modified</lit> and/or 
     
    180178class Connect(object): 
    181179    """ 
    182     <par><class>Connect</class> objects can be used as decorators that wraps 
    183     a function that needs a database connection.</par> 
     180    <p><class>Connect</class> objects can be used as decorators that wraps 
     181    a function that needs a database connection.</p> 
    184182     
    185     <par>If calling the wrapped function results in a database exception 
     183    <p>If calling the wrapped function results in a database exception 
    186184    that has been caused by a lost connection to the database or similar problems, 
    187     the function is retried with a new database connection.</par> 
     185    the function is retried with a new database connection.</p> 
    188186    """ 
    189187    _badoracleexceptions = set(( 
     
    213211        object) must be specified. <arg>retry</arg> specifies how often to retry 
    214212        calling the wrapped function after a database exception. <arg>kwargs</arg> 
    215         will be passed on the the <function>connect</function> call. 
     213        will be passed on the the <func>connect</func> call. 
    216214        """ 
    217215        if (connectstring is not None) == (pool is not None): 
     
    254252                    # This only works if func is using the same connection 
    255253                    return func(*args, **kwargs) 
    256                 except cx_Oracle.DatabaseError, exc: 
     254                except orasql.DatabaseError, exc: 
    257255                    if i<self.retry-1 and self._isbadoracleexception(exc): 
    258256                        # Drop bad connection and retry 
     
    268266class Call(object): 
    269267    """ 
    270     <par>Wrap an Oracle procedure or function in a CherryPy handler.</par> 
    271  
    272     <par><class>Call</class> object wraps a procedure or function object from 
    273     <pyref module="ll.orasql"><module>ll.orasql</module></pyref> and makes it 
     268    <p>Wrap an Oracle procedure or function in a CherryPy handler.</p> 
     269 
     270    <p><class>Call</class> object wraps a procedure or function object from 
     271    <pyref module="ll.orasql"><mod>ll.orasql</mod></pyref> and makes it 
    274272    callable just like a CherryPy handler. 
    275273    """ 
     
    286284    def __call__(self, *args, **kwargs): 
    287285        """ 
    288         <par>Call the procedure/function with the arguments <arg>args</arg> and 
     286        <p>Call the procedure/function with the arguments <arg>args</arg> and 
    289287        <arg>kwargs</arg> mapping Python function arguments to Oracle procedure/function 
    290288        arguments. On return from the procedure the <lit>c_out</lit> parameter is 
     
    294292        <lit>p_etag</lit> (a string) and <lit>p_cachecontrol</lit> (a string) 
    295293        are mapped to the appropriate CherryPy response headers. If 
    296         <lit>p_etag</lit> is not specified a value is calculated.</par> 
    297         <par>If the procedure/function raised a PL/SQL exception with a code between 
     294        <lit>p_etag</lit> is not specified a value is calculated.</p> 
     295        <p>If the procedure/function raised a PL/SQL exception with a code between 
    298296        20200 and 20599, 20000 will be substracted from this value and the resulting 
    299297        value will be used as the HTTP response code, i.e. 20404 will give a 
     
    310308                    return self.callable(cursor, *args, **kwargs) 
    311309                return (body, result) 
    312             except cx_Oracle.DatabaseError, exc: 
     310            except orasql.DatabaseError, exc: 
    313311                if exc.args: 
    314312                    code = getattr(exc[0], "code", 0)