Add _dns module docs

diff --git a/docs/api/_dns.rst b/docs/api/_dns.rst
new file mode 100644 (file)
index 0000000..14c1e40
--- /dev/null
+++ b/docs/api/_dns.rst
@@ -0,0 +1,62 @@
+`_dns` -- DNS resolution utilities
+==================================
+
+.. module:: psycopg._dns
+
+This module contains a few experimental utilities to interact wit the DNS
+server before performing a connection.
+
+.. warning::
+    This module is experimental and its interface could change in the future,
+    without warning or respect for the version scheme. It is provided here to
+    allow experimentation before making it more stable.
+
+.. warning::
+    This module depends on the `dnspython`_ package. The package is currently
+    not installed automatically as a Psycopg dependency and must be installed
+    manually:
+
+    .. code:: sh
+
+        $ pip install "dnspython >= 2.1"
+
+    .. _dnspython: https://dnspython.readthedocs.io/
+
+
+.. autofunction:: resolve_hostaddr_async
+
+   .. note::
+       One possible way to use this function automatically is to subclass
+       `~psycopg.AsyncConnection`, extending the
+       `~psycopg.AsyncConnection._get_connection_params()` method::
+
+           import psycopg._dns  # not imported automatically
+
+           class AsyncDnsConnection(psycopg.AsyncConnection):
+               @classmethod
+               async def _get_connection_params(cls, conninfo, **kwargs):
+                   params = await super()._get_connection_params(conninfo, **kwargs)
+                   params = await psycopg._dns.resolve_hostaddr_async(params)
+                   return params
+
+
+.. automethod:: psycopg.Connection._get_connection_params
+
+    .. warning::
+        This is an experimental method.
+
+    This method is a subclass hook allowing to manipulate the connection
+    parameters before performing the connection. Make sure to call the
+    `!super()` implementation before further manipulation of the arguments::
+
+        @classmethod
+        def _get_connection_params(cls, conninfo, **kwargs):
+            params = super()._get_connection_params(conninfo, **kwargs)
+            # do something with the params
+            return params
+
+
+.. automethod:: psycopg.AsyncConnection._get_connection_params
+
+   .. warning::
+       This is an experimental method.

diff --git a/docs/api/index.rst b/docs/api/index.rst
index e605c0b8b2c1a1982df5c67c0af639197237b8a6..ec425fd4afdf27de0a060cd07e584a2881338d33 100644 (file)
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -23,3 +23,4 @@ This sections is a reference for all the public objects exposed by the
     abc
     pq
     pool
+    _dns

diff --git a/psycopg/psycopg/_dns.py b/psycopg/psycopg/_dns.py
index 4c7798830ea442c0f94ad6419bcdf50ad0783340..f4ac6ffe62f9cd510ca244a03e5317d182a5e529 100644 (file)
--- a/psycopg/psycopg/_dns.py
+++ b/psycopg/psycopg/_dns.py
@@ -30,15 +30,18 @@ async def resolve_hostaddr_async(params: Dict[str, Any]) -> Dict[str, Any]:
     """
     Perform async DNS lookup of the hosts and return a new params dict.
 
+    :param params: The input parameters, for instance as returned by
+        `~psycopg.conninfo.conninfo_to_dict()`.
+
     If a ``host`` param is present but not ``hostname``, resolve the host
     addresses dynamically.
 
-    Change ``host``, ``hostname``, ``port`` in place to allow to connect
-    without further DNS lookups (remove hosts that are not resolved, keep the
-    lists consistent).
+    The function may change the input ``host``, ``hostname``, ``port`` to allow
+    to connect without further DNS lookups, eventually removing hosts that are
+    not resolved, keeping the lists of hosts and ports consistent.
 
-    Raise `OperationalError` if connection is not possible (e.g. no host
-    resolve, inconsistent lists length).
+    Raise `~psycopg.OperationalError` if connection is not possible (e.g. no
+    host resolve, inconsistent lists length).
 
     See `the PostgreSQL docs`__ for explanation of how these params are used,
     and how they support multiple entries.
@@ -47,7 +50,7 @@ async def resolve_hostaddr_async(params: Dict[str, Any]) -> Dict[str, Any]:
            #LIBPQ-PARAMKEYWORDS
 
     .. warning::
-        This function doesn't handle the ``/etc/hosts`` file.
+        This function currently doesn't handle the ``/etc/hosts`` file.
     """
     host_arg: str = params.get("host", os.environ.get("PGHOST", ""))
     hostaddr_arg = params.get("hostaddr", os.environ.get("PGHOSTADDR", ""))

diff --git a/psycopg/psycopg/connection.py b/psycopg/psycopg/connection.py
index ee6b3981a731f3c238bf405f3eaee60a9a0a23c2..5999f6ac06e6c22fccfa52a3a85b6f73bafcaf68 100644 (file)
--- a/psycopg/psycopg/connection.py
+++ b/psycopg/psycopg/connection.py
@@ -616,7 +616,13 @@ class Connection(BaseConnection[Row]):
     def _get_connection_params(
         cls, conninfo: str, **kwargs: Any
     ) -> Dict[str, Any]:
-        """Adjust connection parameters before conecting."""
+        """Manipulate connection parameters before connecting.
+
+        :param conninfo: Connection string as received by `~Connection.connect()`.
+        :param kwargs: Overriding connection arguments as received by `!connect()`.
+        :return: Connection arguments merged and eventually modified, in a
+            format similar to `~conninfo.conninfo_to_dict()`.
+        """
         params = conninfo_to_dict(conninfo, **kwargs)
 
         # Make sure there is an usable connect_timeout

diff --git a/psycopg/psycopg/connection_async.py b/psycopg/psycopg/connection_async.py
index d14e194315226310224c52bf416415fbf55488a8..38c032ff13374660257736641feb2cb890aab476 100644 (file)
--- a/psycopg/psycopg/connection_async.py
+++ b/psycopg/psycopg/connection_async.py
@@ -130,7 +130,7 @@ class AsyncConnection(BaseConnection[Row]):
     async def _get_connection_params(
         cls, conninfo: str, **kwargs: Any
     ) -> Dict[str, Any]:
-        """Adjust connection parameters before conecting."""
+        """Manipulate connection parameters before connecting."""
         params = conninfo_to_dict(conninfo, **kwargs)
 
         # Make sure there is an usable connect_timeout

diff --git a/psycopg/setup.py b/psycopg/setup.py
index cd3a1da5bad2d2473f4db49386e46e6e2fac480c..2f689a169e20f92de2d089449080886de8961494 100644 (file)
--- a/psycopg/setup.py
+++ b/psycopg/setup.py
@@ -54,6 +54,7 @@ extras_require = {
     # Requirements needed to build the documentation
     "docs": [
         "Sphinx >= 4.1, < 4.2",
+        "dnspython >= 2.1.0",  # to become a package dependency
         "docutils >= 0.17, < 0.18",
         "furo >= furo-2021.8.17b43",
         "sphinx-autobuild >= 2021.3.14",