Merge branch 'master' into feature/replication-protocol-c-connection-object

3 files changed, 122 insertions, 58 deletions

diff --git a/doc/src/advanced.rst b/doc/src/advanced.rst
index 82754ee..e63fcff 100644
--- a/doc/src/advanced.rst
+++ b/doc/src/advanced.rst
@@ -270,7 +270,7 @@ wasting resources.
 
 A simple application could poll the connection from time to time to check if
 something new has arrived. A better strategy is to use some I/O completion
-function such as :py:func:`~select.select` to sleep until awaken from the kernel when there is
+function such as :py:func:`~select.select` to sleep until awakened by the kernel when there is
 some data to read on the connection, thereby using no CPU unless there is
 something to read::
 
diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst
index dcaa234..1a0e154 100644
--- a/doc/src/extensions.rst
+++ b/doc/src/extensions.rst
@@ -12,17 +12,12 @@
 The module contains a few objects and function extending the minimum set of
 functionalities defined by the |DBAPI|_.
 
-.. function:: parse_dsn(dsn)
-
-    Parse connection string into a dictionary of keywords and values.
-
-    Uses libpq's ``PQconninfoParse`` to parse the string according to
-    accepted format(s) and check for supported keywords.
+Classes definitions
+-------------------
 
-    Example::
-
-        >>> psycopg2.extensions.parse_dsn('dbname=test user=postgres password=secret')
-        {'password': 'secret', 'user': 'postgres', 'dbname': 'test'}
+Instances of these classes are usually returned by factory functions or
+attributes. Their definitions are exposed here to allow subclassing,
+introspection etc.
 
 .. function:: make_dsn(**kwargs)
 
@@ -56,6 +51,7 @@ functionalities defined by the |DBAPI|_.
 
     For a complete description of the class, see `connection`.
 
+
 .. class:: cursor(conn, name=None)
 
     It is the class usually returned by the `connection.cursor()`
@@ -66,6 +62,7 @@ functionalities defined by the |DBAPI|_.
 
     For a complete description of the class, see `cursor`.
 
+
 .. class:: lobject(conn [, oid [, mode [, new_oid [, new_file ]]]])
 
     Wrapper for a PostgreSQL large object. See :ref:`large-objects` for an
@@ -222,39 +219,6 @@ functionalities defined by the |DBAPI|_.
         server versions.
 
 
-.. autofunction:: set_wait_callback(f)
-
-    .. versionadded:: 2.2.0
-
-.. autofunction:: get_wait_callback()
-
-    .. versionadded:: 2.2.0
-
-.. function:: libpq_version()
-
-    Return the version number of the ``libpq`` dynamic library loaded as an
-    integer, in the same format of `~connection.server_version`.
-
-    Raise `~psycopg2.NotSupportedError` if the ``psycopg2`` module was
-    compiled with a ``libpq`` version lesser than 9.1 (which can be detected
-    by the `~psycopg2.__libpq_version__` constant).
-
-    .. seealso:: libpq docs for `PQlibVersion()`__.
-
-        .. __: http://www.postgresql.org/docs/current/static/libpq-misc.html#LIBPQ-PQLIBVERSION
-
-.. function:: quote_ident(str, scope)
-
-    Return quoted identifier according to PostgreSQL quoting rules.
-
-    The *scope* must be a `connection` or a `cursor`, the underlying
-    connection encoding is used for any necessary character conversion.
-
-    Requires libpq >= 9.0.
-
-    .. seealso:: libpq docs for `PQescapeIdentifier()`__
-
-        .. __: http://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER
 
 .. _sql-adaptation-objects:
 
@@ -514,6 +478,106 @@ The module exports a few exceptions in addition to the :ref:`standard ones
 
 
 
+.. _coroutines-functions:
+
+Coroutines support functions
+----------------------------
+
+These functions are used to set and retrieve the callback function for
+:ref:`cooperation with coroutine libraries <green-support>`.
+
+.. versionadded:: 2.2.0
+
+.. autofunction:: set_wait_callback(f)
+
+.. autofunction:: get_wait_callback()
+
+
+
+Other functions
+---------------
+
+.. function:: libpq_version()
+
+    Return the version number of the ``libpq`` dynamic library loaded as an
+    integer, in the same format of `~connection.server_version`.
+
+    Raise `~psycopg2.NotSupportedError` if the ``psycopg2`` module was
+    compiled with a ``libpq`` version lesser than 9.1 (which can be detected
+    by the `~psycopg2.__libpq_version__` constant).
+
+    .. versionadded:: 2.7
+
+    .. seealso:: libpq docs for `PQlibVersion()`__.
+
+        .. __: http://www.postgresql.org/docs/current/static/libpq-misc.html#LIBPQ-PQLIBVERSION
+
+
+.. function:: make_dsn(dsn=None, \*\*kwargs)
+
+    Create a valid 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 name is specified in both the sources, the *kwargs* value
+    overrides the *dsn* value.
+
+    The input arguments are validated: the output should always be a valid
+    connection string (as far as `parse_dsn()` is concerned). If not raise
+    `~psycopg2.ProgrammingError`.
+
+    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.
+
+    Parsing is delegated to the libpq: different versions of the client
+    library may support different formats or parameters (for example,
+    `connection URIs`__ are only supported from libpq 9.2).  Raise
+    `~psycopg2.ProgrammingError` if the *dsn* is not valid.
+
+    .. __: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
+
+    Example::
+
+        >>> from psycopg2.extensions import parse_dsn
+        >>> parse_dsn('dbname=test user=postgres password=secret')
+        {'password': 'secret', 'user': 'postgres', 'dbname': 'test'}
+        >>> parse_dsn("postgresql://someone@example.com/somedb?connect_timeout=10")
+        {'host': 'example.com', 'user': 'someone', 'dbname': 'somedb', 'connect_timeout': '10'}
+
+    .. versionadded:: 2.7
+
+    .. seealso:: libpq docs for `PQconninfoParse()`__.
+
+        .. __: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNINFOPARSE
+
+
+.. function:: quote_ident(str, scope)
+
+    Return quoted identifier according to PostgreSQL quoting rules.
+
+    The *scope* must be a `connection` or a `cursor`, the underlying
+    connection encoding is used for any necessary character conversion.
+
+    Requires libpq >= 9.0.
+
+    .. versionadded:: 2.7
+
+    .. seealso:: libpq docs for `PQescapeIdentifier()`__
+
+        .. __: http://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER
+
+
+
 .. index::
     pair: Isolation level; Constants
 
diff --git a/doc/src/module.rst b/doc/src/module.rst
index 6950b70..97fbdf1 100644
--- a/doc/src/module.rst
+++ b/doc/src/module.rst
@@ -17,37 +17,34 @@ 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=None, 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.
+    Note that either the *dsn* or at least one connection-related keyword
+    argument is required.
 
     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)
     - `!port` -- connection port number (defaults to 5432 if not provided)
 
     Any other connection parameter supported by the client library/server can
-    be passed either in the connection string or as keywords. The PostgreSQL
+    be passed either in the connection string or as a keyword. The PostgreSQL
     documentation contains the complete list of the `supported parameters`__.
     Also note that the same parameters can be passed to the client library
     using `environment variables`__.
@@ -76,6 +73,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`
@@ -89,8 +89,8 @@ The module interface respects the standard defined in the |DBAPI|_.
 
     .. extension::
 
-        The parameters *connection_factory* and *async* are Psycopg extensions
-        to the |DBAPI|.
+        The non-connection-related keyword parameters are Psycopg extensions
+        to the |DBAPI|_.
 
 .. data:: apilevel