From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sun, 29 Aug 2021 16:55:08 +0000 (+0200)
Subject: Add docs for conninfo module
X-Git-Tag: 3.0.beta1~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2a55a8e905ef1c3858f9a022141ac8d13a7e0ecf;p=thirdparty%2Fpsycopg.git

Add docs for conninfo module
---

diff --git a/docs/api/conninfo.rst b/docs/api/conninfo.rst
new file mode 100644
index 000000000..9e5b01da2
--- /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 b466f55ca..e605c0b8b 100644
--- 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 058eaf663..a920d0d61 100644
--- 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 = {