From: Eric Siegerman <eric.siegerman@rci.rogers.com>
Date: Wed, 23 Sep 2015 20:39:11 +0000 (-0400)
Subject: Add a lot more detail
X-Git-Tag: rel_1_1_0b1~84^2~70^2~98
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0854f82993c9bc07a64cc52bb4c092d1f5f11b8c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Add a lot more detail

(cherry picked from commit 5db5e18d3babdb3ee857c075c774a585505b78ce)
---

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index 4b6e752ba7..0b0d50329a 100644
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -389,14 +389,33 @@ def create_engine(*args, **kwargs):
 def engine_from_config(configuration, prefix='sqlalchemy.', **kwargs):
     """Create a new Engine instance using a configuration dictionary.
 
-    The *configuration* dictionary is typically produced from a config file
-    in which keys are prefixed, e.g. ``sqlalchemy.url``, ``sqlalchemy.echo``,
-    etc.  The 'prefix' argument indicates the prefix to be searched for.
+    The dictionary is typically produced from a config file.
+    
+    The keys of interest to ``engine_from_config()`` should be prefixed, e.g.
+    ``sqlalchemy.url``, ``sqlalchemy.echo``, etc.  The 'prefix' argument
+    indicates the prefix to be searched for.  Each matching key (after the
+    prefix is stripped) is treated as though it were the corresponding keyword
+    argument to a :func:`.create_engine` call.
+
+    The only required key is (assuming the default prefix) ``sqlalchemy.url``,
+    which provides the :ref:`database URL <database_urls>`.
 
     A select set of keyword arguments will be "coerced" to their
     expected type based on string values.    The set of arguments
     is extensible per-dialect using the ``engine_config_types`` accessor.
 
+    :param configuration: A dictionary (typically produced from a config file,
+        but this is not a requirement).  Items whose keys start with the value
+        of 'prefix' will have that prefix stripped, and will then be passed to
+        :ref:`create_engine`.
+
+    :param prefix: Prefix to match and then strip from keys
+        in 'configuration'.
+
+    :param kwargs: Each keyword argument to ``engine_from_config()`` itself
+        overrides the corresponding item taken from the 'configuration'
+        dictionary.  Keyword arguments should *not* be prefixed.
+
     """
 
     options = dict((key[len(prefix):], configuration[key])