From 6893295a8794f332cb9c2a667001ba7dcefb880b Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 3 Mar 2016 16:08:09 +0000
Subject: [PATCH] Added docs about make_dsn

connect() docs updated to document the arguments merging.
---
 doc/src/extensions.rst | 24 +++++++++++++++++++++++-
 doc/src/module.rst     | 20 +++++++++-----------
 lib/__init__.py        |  4 ++--
 3 files changed, 34 insertions(+), 14 deletions(-)

diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst
index 68619e5f..594ffc03 100644
--- a/doc/src/extensions.rst
+++ b/doc/src/extensions.rst
@@ -491,6 +491,27 @@ Other functions
         .. __: http://www.postgresql.org/docs/current/static/libpq-misc.html#LIBPQ-PQLIBVERSION
 
 
+.. function:: make_dsn(dsn=None, \*\*kwargs)
+
+    Create a connection string from arguments.
+
+    Put together the arguments in *kwargs* into a connection string. If *dsn*
+    is specified too, merge the arguments coming from both the sources. If the
+    same argument is specified in both the sources, the *kwargs* version
+    overrides the *dsn* version
+
+    At least one param is required (either *dsn* or any keyword). Note that
+    the empty string is a valid connection string.
+
+    Example::
+
+        >>> from psycopg2.extensions import make_dsn
+        >>> make_dsn('dbname=foo host=example.com', password="s3cr3t")
+        'host=example.com password=s3cr3t dbname=foo'
+
+    .. versionadded:: 2.7
+
+
 .. function:: parse_dsn(dsn)
 
     Parse connection string into a dictionary of keywords and values.
@@ -500,7 +521,8 @@ Other functions
 
     Example::
 
-        >>> psycopg2.extensions.parse_dsn('dbname=test user=postgres password=secret')
+        >>> from psycopg2.extensions import parse_dsn
+        >>> parse_dsn('dbname=test user=postgres password=secret')
         {'password': 'secret', 'user': 'postgres', 'dbname': 'test'}
 
     .. versionadded:: 2.7
diff --git a/doc/src/module.rst b/doc/src/module.rst
index 6950b703..25a9ba27 100644
--- a/doc/src/module.rst
+++ b/doc/src/module.rst
@@ -17,30 +17,25 @@ The module interface respects the standard defined in the |DBAPI|_.
     single: DSN (Database Source Name)
 
 .. function::
-    connect(dsn, connection_factory=None, cursor_factory=None, async=False)
-    connect(\*\*kwargs, connection_factory=None, cursor_factory=None, async=False)
+    connect(dsn, connection_factory=None, cursor_factory=None, async=False, \*\*kwargs)
 
     Create a new database session and return a new `connection` object.
 
-    The connection parameters can be specified either as a `libpq connection
+    The connection parameters can be specified as a `libpq connection
     string`__ using the *dsn* parameter::
 
         conn = psycopg2.connect("dbname=test user=postgres password=secret")
 
     or using a set of keyword arguments::
 
-        conn = psycopg2.connect(database="test", user="postgres", password="secret")
+        conn = psycopg2.connect(dbname"test", user="postgres", password="secret")
 
-    The two call styles are mutually exclusive: you cannot specify connection
-    parameters as keyword arguments together with a connection string; only
-    the parameters not needed for the database connection (*i.e.*
-    *connection_factory*, *cursor_factory*, and *async*) are supported
-    together with the *dsn* argument.
+    or using a mix of both: if the same parameter name is specified in both
+    sources the *kwargs* value will have precedence over the *dsn* value.
 
     The basic connection parameters are:
 
-    - `!dbname` -- the database name (only in the *dsn* string)
-    - `!database` -- the database name (only as keyword argument)
+    - `!dbname` -- the database name (`!database` is a deprecated alias)
     - `!user` -- user name used to authenticate
     - `!password` -- password used to authenticate
     - `!host` -- database host address (defaults to UNIX socket if not provided)
@@ -76,6 +71,9 @@ The module interface respects the standard defined in the |DBAPI|_.
     .. versionchanged:: 2.5
         added the *cursor_factory* parameter.
 
+    .. versionchanged:: 2.7
+        both *dsn* and keyword arguments can be specified.
+
     .. seealso::
 
         - `~psycopg2.extensions.parse_dsn`
diff --git a/lib/__init__.py b/lib/__init__.py
index 4a288197..698f50d6 100644
--- a/lib/__init__.py
+++ b/lib/__init__.py
@@ -86,7 +86,7 @@ def connect(dsn=None, connection_factory=None, cursor_factory=None,
     """
     Create a new database connection.
 
-    The connection parameters can be specified either as a string:
+    The connection parameters can be specified as a string:
 
         conn = psycopg2.connect("dbname=test user=postgres password=secret")
 
@@ -94,7 +94,7 @@ def connect(dsn=None, connection_factory=None, cursor_factory=None,
 
         conn = psycopg2.connect(database="test", user="postgres", password="secret")
 
-    The basic connection parameters are:
+    Or as a mix of both. The basic connection parameters are:
 
     - *dbname*: the database name
     - *database*: the database name (only as keyword argument)