Add docs for conninfo module

diff --git a/docs/api/conninfo.rst b/docs/api/conninfo.rst
new file mode 100644 (file)
index 0000000..9e5b01d
--- /dev/null
+++ b/docs/api/conninfo.rst
@@ -0,0 +1,24 @@
+.. _psycopg.conninfo:
+
+`conninfo` -- manipulate connection strings
+===========================================
+
+This module contains a few utility functions to manipulate database
+connection strings.
+
+.. module:: psycopg.conninfo
+
+.. autofunction:: conninfo_to_dict
+
+   .. code:: python
+
+       >>> conninfo_to_dict("postgres://jeff@example.com/db", user="piro")
+       {'user': 'piro', 'dbname': 'db', 'host': 'example.com'}
+
+
+.. autofunction:: make_conninfo
+
+   .. code:: python
+
+        >>> make_conninfo("dbname=db user=jeff", user="piro", port=5432)
+        'dbname=db user=piro port=5432'

diff --git a/docs/api/index.rst b/docs/api/index.rst
index b466f55ca43b453d9c3b54c655b19988e6fdab16..e605c0b8b2c1a1982df5c67c0af639197237b8a6 100644 (file)
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -17,6 +17,7 @@ This sections is a reference for all the public objects exposed by the
     sql
     rows
     errors
+    conninfo
     adapt
     types
     abc

diff --git a/psycopg/psycopg/conninfo.py b/psycopg/psycopg/conninfo.py
index 058eaf6633e095119ddda345fa564e8458c89f2a..a920d0d61d7a399e9290d3a01a2669493ef53bb2 100644 (file)
--- a/psycopg/psycopg/conninfo.py
+++ b/psycopg/psycopg/conninfo.py
@@ -19,7 +19,15 @@ def make_conninfo(conninfo: str = "", **kwargs: Any) -> str:
     """
     Merge a string and keyword params into a single conninfo string.
 
-    Raise ProgrammingError if the input don't make a valid conninfo.
+    :param conninfo: A `connection string`__ as accepted by PostgreSQL.
+    :param kwargs: Parameters overriding the ones specified in *conninfo*.
+    :return: A connection string valid for PostgreSQL, with the *kwargs*
+        parameters merged.
+
+    Raise `~psycopg.ProgrammingError` if the input don't make a valid conninfo.
+
+    .. __: https://www.postgresql.org/docs/current/libpq-connect.html
+           #LIBPQ-CONNSTRING
     """
     if not conninfo and not kwargs:
         return ""
@@ -53,7 +61,15 @@ def conninfo_to_dict(conninfo: str = "", **kwargs: Any) -> Dict[str, Any]:
     """
     Convert the *conninfo* string into a dictionary of parameters.
 
+    :param conninfo: A `connection string`__ as accepted by PostgreSQL.
+    :param kwargs: Parameters overriding the ones specified in *conninfo*.
+    :return: Dictionary with the parameters parsed from *conninfo* and
+        *kwargs*.
+
     Raise ProgrammingError if the string is not valid.
+
+    .. __: https://www.postgresql.org/docs/current/libpq-connect.html
+           #LIBPQ-CONNSTRING
     """
     opts = _parse_conninfo(conninfo)
     rv = {