From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 27 Oct 2005 04:11:59 +0000 (+0000)
Subject: (no commit message)
X-Git-Tag: rel_0_1_0~442
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5a154978fe1c504910c2a95104807e2a4a1febdc;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

---

diff --git a/doc/build/components/pydoc.myt b/doc/build/components/pydoc.myt
index 4acf6592c1..07191b242c 100644
--- a/doc/build/components/pydoc.myt
+++ b/doc/build/components/pydoc.myt
@@ -1,6 +1,8 @@
 <%method obj_doc>
     <%args>
         obj
+        functions = None
+        classes = None
     </%args>
     <%init>
         import types
@@ -12,55 +14,61 @@
                 objects = obj.__ALL__
             else:
                 objects = obj.__dict__.keys()
-            functions = [getattr(obj, x, None) 
-                for x in objects 
-                if getattr(obj,x,None) is not None and 
-                    (isinstance(getattr(obj,x), types.FunctionType))
-                    and not getattr(obj,x).__name__[0] == '_'
-                ]
-            classes = [getattr(obj, x, None) 
-                for x in objects 
-                if getattr(obj,x,None) is not None and 
-                    (isinstance(getattr(obj,x), types.TypeType) 
-                    or isinstance(getattr(obj,x), types.ClassType))
-                    and not getattr(obj,x).__name__[0] == '_'
-                ]
+            if functions is None:
+                functions = [getattr(obj, x, None) 
+                    for x in objects 
+                    if getattr(obj,x,None) is not None and 
+                        (isinstance(getattr(obj,x), types.FunctionType))
+                        and not getattr(obj,x).__name__[0] == '_'
+                    ]
+                functions.sort(lambda a, b: cmp(a.__name__, b.__name__))
+            if classes is None:
+                classes = [getattr(obj, x, None) 
+                    for x in objects 
+                    if getattr(obj,x,None) is not None and 
+                        (isinstance(getattr(obj,x), types.TypeType) 
+                        or isinstance(getattr(obj,x), types.ClassType))
+                        and not getattr(obj,x).__name__[0] == '_'
+                    ]
+                classes.sort(lambda a, b: cmp(a.__name__, b.__name__))
         else:
-            functions = [getattr(obj, x).im_func for x in obj.__dict__.keys() if isinstance(getattr(obj,x), types.MethodType) and not getattr(obj,x).__name__[0] == '_']
-            classes = []
+            if functions is None:
+                functions = [getattr(obj, x).im_func for x in obj.__dict__.keys() if isinstance(getattr(obj,x), types.MethodType) and not getattr(obj,x).__name__[0] == '_']
+                functions.sort(lambda a, b: cmp(a.__name__, b.__name__))
+            if classes is None:
+                classes = []
             
-        functions.sort(lambda a, b: cmp(a.__name__, b.__name__))
-        classes.sort(lambda a, b: cmp(a.__name__, b.__name__))
+        if isclass:
+            description = "Class " + name
+        else:
+            description = "Module " + name
     </%init>
 
-<h2>
-% if isclass:
-    Class <% name %>
-% else:
-    Module <% name %>
-%
-</h2>
+<&|doclib.myt:item, name=obj.__name__, description=description &>
+
 <% obj.__doc__ %>
-<br/>
+<% (obj.__doc__ and "<br/><br/>" or '') %>
 
+% if len(functions):
 <&|formatting.myt:paramtable&>
-% if not isclass and len(functions):
-    <h3>Module Functions</h3>
 %   for func in functions:
-hi
     <& SELF:function_doc, func=func &>
 %
+</&>
 %
 
 % if len(classes):
     <h3>Classes</h3>
+<&|formatting.myt:paramtable&>
 %   for class_ in classes:
       <& SELF:obj_doc, obj=class_ &>
 %   
+</&>
 %    
+
 </&>
-</%method>
 
+</%method>
 
 <%method function_doc>
     <%args>func</%args>
@@ -72,21 +80,17 @@ hi
         varkw = argspec[2]
         defaults = argspec[3] or ()
         argstrings = []
-        i = 0
-        for arg in argnames:
-            try:
-                default = defaults[i]
-                argstrings.append("%s=%s" % (arg, repr(default)))
-                i +=1
-            except IndexError:
-                argstrings.append(arg)
+        for i in range(0, len(argnames)):
+            if i >= len(argnames) - len(defaults):
+                argstrings.append("%s=%s" % (argnames[i], repr(defaults[i - (len(argnames) - len(defaults))])))
+            else:
+                argstrings.append(argnames[i])
         if varargs is not None:
            argstrings.append("*%s" % varargs)
         if varkw is not None:
            argstrings.append("**%s" % varkw)
     </%init>
     
-    huh ? <% repr(func) |h %>
     <&| formatting.myt:function_doc, name="def " + func.__name__, arglist=argstrings &>
     <% func.__doc__ %>
     </&>
diff --git a/doc/build/content/pooling.myt b/doc/build/content/pooling.myt
index c1fb89e114..ec7a23ca77 100644
--- a/doc/build/content/pooling.myt
+++ b/doc/build/content/pooling.myt
@@ -1,8 +1,30 @@
 <%flags>inherit='document_base.myt'</%flags>
 <&|doclib.myt:item, name="pooling", description="Connection Pooling" &>
     <&|doclib.myt:item, name="establishing", description="Establishing a Transparent Connection Pool" &>
+    Any DBAPI module can be "proxied" through the connection pool using the following technique:
+    
+    <&|formatting.myt:code&>
+    import sqlalchemy.pool as pool
+    import psycopg2 as psycopg
+    psycopg = pool.manage(psycopg)
+    
+    # then connect normally
+    connection = psycopg.connect(database='test', username='scott', password='tiger')
+    </&>
+    <p>This produces a <span class="codeline">sqlalchemy.pool.DBProxy</span> object which supports the same <span class="codeline">connect()</span> function as the original DBAPI module.  Upon connection, a thread-local connection proxy object is returned, which delegates its calls to a real DBAPI connection object.  This connection object is stored persistently within a connection pool (an instance of <span class="codeline">sqlalchemy.pool.Pool</span>) that corresponds to the exact connection arguments sent to the <span class="codeline">connect()</span> function.  The connection proxy also returns a proxied cursor object upon calling <span class="codeline">connection.cursor()</span>.  When all cursors as well as the connection proxy are de-referenced, the connection is automatically made available again by the owning pool object.</p>
+    
+    <p>Basically, the <span class="codeline">connect()</span> function is used in its usual way, and the pool module transparently returns thread-local pooled connections.  Each distinct set of connect arguments corresponds to a brand new connection pool created; in this way, an application can maintain connections to multiple schemas and/or databases, and each unique connect argument set will be managed by a different pool object.</p>
     </&>
 
     <&|doclib.myt:item, name="configuration", description="Connection Pool Configuration" &>
+    <p>When proxying a DBAPI module through the <span class="codeline">pool</span> module, options exist for how the connections should be pooled:
+    </p>
+    <ul>
+        <li>echo=False : if set to True, connections being pulled and retrieved from/to the pool will be logged to the standard output, as well as pool sizing information.</li>
+        <li>use_threadlocal=True : if set to True, repeated calls to connect() within the same application thread will be guaranteed to return the <b>same</b> connection object, if one has already been retrieved from the pool and has not been returned yet.  This allows code to retrieve a connection from the pool, and then while still holding on to that connection, to call other functions which also ask the pool for a connection of the same arguments;  those functions will act upon the same connection that the calling method is using.</li>
+        <li>poolclass=QueuePool :  the default class used by the pool module to provide pooling.  QueuePool uses the Python <span class="codeline">Queue.Queue</span> class to maintain a list of available connections.</li>
+        <li>pool_size=5 : used by QueuePool - the size of the pool to be maintained.  This is the largest number of connections that will be kept persistently in the pool.  Note that the pool begins with no connections; once this number of connections is requested, that number of connections will remain.</li>
+        <li>max_overflow=10 : the maximum overflow size of the pool.  When the number of checked-out connections reaches the size set in pool_size, additional connections will be returned up to this limit.  When those additional connections are returned to the pool, they are disconnected and discarded.  It follows then that the total number of simultaneous connections the pool will allow is pool_size + max_overflow, and the total number of "sleeping" connections the pool will allow is pool_size.  max_overflow can be set to -1 to indicate no overflow limit; no limit will be placed on the total number of concurrent connections.</li>
+    </ul>
     </&>
 </&>
\ No newline at end of file
diff --git a/doc/style.css b/doc/style.css
index 6decd245de..ddef5196d8 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -30,7 +30,7 @@ a:hover {color:#700000;}
 }
 
 .light {
-	background-color: #FFFFFF;
+	background-color: #EFEFEF;
 }
 
 .dark {