From 110846f601818aed47120060370a2675efce0bd3 Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 12 Oct 2006 22:12:39 +0000
Subject: [PATCH] added docstrings for url, added to compiled documentation

---
 doc/build/compile_docstrings.py |  1 +
 lib/sqlalchemy/engine/url.py    | 36 +++++++++++++++++++++++++++++----
 2 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/doc/build/compile_docstrings.py b/doc/build/compile_docstrings.py
index 59909d8f26..44135b6ed0 100644
--- a/doc/build/compile_docstrings.py
+++ b/doc/build/compile_docstrings.py
@@ -24,6 +24,7 @@ def make_doc(obj, classes=None, functions=None):
 make_doc(obj=sql, classes=[])
 make_doc(obj=schema)
 make_doc(obj=engine, classes=[engine.Connectable, engine.ComposedSQLEngine, engine.Connection, engine.Transaction, engine.Dialect, engine.ConnectionProvider, engine.ExecutionContext, engine.ResultProxy, engine.RowProxy])
+make_doc(obj=engine.url)
 make_doc(obj=orm)
 make_doc(obj=orm.session, classes=[orm.session.Session, orm.session.SessionTransaction])
 make_doc(obj=pool, classes=[pool.DBProxy, pool.Pool, pool.QueuePool, pool.SingletonThreadPool])
diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py
index 7c3d947ca8..9b0e9f39ec 100644
--- a/lib/sqlalchemy/engine/url.py
+++ b/lib/sqlalchemy/engine/url.py
@@ -3,7 +3,30 @@ import cgi
 import urllib
 import sqlalchemy.exceptions as exceptions
 
+"""provides the URL object as well as the make_url parsing function."""
+
 class URL(object):
+    """represents the components of a URL used to connect to a database.
+    
+    This object is suitable to be passed directly to a create_engine() call.
+    The fields of the URL are parsed from a string by the module-level make_url() function.  
+    the string format of the URL is an RFC-1738-style string.  
+    
+    Attributes on URL include:
+    
+    drivername
+    
+    username
+    
+    password
+    
+    host
+    
+    port
+    
+    database
+    
+    query - a dictionary containing key/value pairs representing the URL's query string."""
     def __init__(self, drivername, username=None, password=None, host=None, port=None, database=None, query=None):
         self.drivername = drivername
         self.username = username
@@ -34,12 +57,13 @@ class URL(object):
             s += '?' + "&".join(["%s=%s" % (k, self.query[k]) for k in keys])
         return s
     def get_module(self):
+        """return the SQLAlchemy database module corresponding to this URL's driver name."""
         return getattr(__import__('sqlalchemy.databases.%s' % self.drivername).databases, self.drivername)
     def translate_connect_args(self, names):
-        """translates this URL's attributes into a dictionary of connection arguments used by a specific dbapi.
-        the names parameter is a list of argument names in the form ('host', 'database', 'user', 'password', 'port')
-        where the given strings match the corresponding argument names for the dbapi.  Will return a dictionary
-        with the dbapi-specific parameters."""
+        """translate this URL's attributes into a dictionary of connection arguments.
+        
+        given a list of argument names corresponding to the URL attributes ('host', 'database', 'username', 'password', 'port'),
+        will assemble the attribute values of this URL into the dictionary using the given names."""
         a = {}
         attribute_names = ['host', 'database', 'username', 'password', 'port']
         for n in names:
@@ -52,6 +76,10 @@ class URL(object):
     
 
 def make_url(name_or_url):
+    """given a string or unicode instance, produces a new URL instance.
+    
+    the given string is parsed according to the rfc1738 spec.
+    if an existing URL object is passed, just returns the object."""
     if isinstance(name_or_url, str) or isinstance(name_or_url, unicode):
         return _parse_rfc1738_args(name_or_url)
     else:
-- 
2.47.2