From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sun, 3 Jul 2022 01:19:56 +0000 (+0100)
Subject: docs: add documentation about async DNS resolution
X-Git-Tag: 3.1~54^2~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=775669c7304f3c6567df083814b0d2b4d1ea85a9;p=thirdparty%2Fpsycopg.git

docs: add documentation about async DNS resolution

Close #259.
---

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index c3a91561e..b1858fb1d 100644
--- a/docs/api/connections.rst
+++ b/docs/api/connections.rst
@@ -414,6 +414,14 @@ The `!AsyncConnection` class
     methods, but should be called using the `await` keyword.
 
     .. automethod:: connect
+
+        .. versionchanged:: 3.1
+
+            Automatically resolve domain names asynchronously. In previous
+            versions, name resolution blocks, unless the ``hostaddr``
+            parameter is specified, or the `~psycopg._dns.resolve_hostaddr_async()`
+            function is used.
+
     .. automethod:: close
 
         .. note:: You can use ``async with`` to close the connection
diff --git a/docs/api/dns.rst b/docs/api/dns.rst
index 84e07b926..2c0904e85 100644
--- a/docs/api/dns.rst
+++ b/docs/api/dns.rst
@@ -23,23 +23,6 @@ server before performing a connection.
     .. _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
-
-
 .. autofunction:: resolve_srv
 
    .. warning::
@@ -86,3 +69,24 @@ server before performing a connection.
 
    .. warning::
        This is an experimental method.
+
+
+.. autofunction:: resolve_hostaddr_async
+
+   .. note::
+       Starting from psycopg 3.1, a similar operation is performed
+       automatically by `!AsyncConnection._get_connection_params()`, so this
+       function is unneeded.
+
+       In psycopg 3.0, 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
diff --git a/docs/news.rst b/docs/news.rst
index 3494f6171..e5f75ef92 100644
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -22,6 +22,8 @@ Psycopg 3.1 (unreleased)
 - `~Cursor.executemany()` performance improved by using batch mode internally
   (:ticket:`#145`).
 - Add parameters to `~Cursor.copy()`.
+- Resolve domain names asynchronously in `AsyncConnection.connect()`
+  (:ticket:`#259`).
 - Add `pq.PGconn.trace()` and related trace functions (:ticket:`#167`).
 - Add ``prepare_threshold`` parameter to `Connection` init (:ticket:`#200`).
 - Add ``cursor_factory`` parameter to `Connection` init.
diff --git a/psycopg/psycopg/_dns.py b/psycopg/psycopg/_dns.py
index cab164012..e7e5ddb59 100644
--- a/psycopg/psycopg/_dns.py
+++ b/psycopg/psycopg/_dns.py
@@ -38,6 +38,11 @@ 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.
 
+    .. deprecated:: 3.1
+        The use of this function is not necessary anymore, because
+        `psycopg.AsyncConnection.connect()` performs non-blocking name
+        resolution automatically.
+
     :param params: The input parameters, for instance as returned by
         `~psycopg.conninfo.conninfo_to_dict()`.
 
diff --git a/psycopg/psycopg/connection_async.py b/psycopg/psycopg/connection_async.py
index 8c6571d0c..1545667b7 100644
--- a/psycopg/psycopg/connection_async.py
+++ b/psycopg/psycopg/connection_async.py
@@ -172,7 +172,15 @@ class AsyncConnection(BaseConnection[Row]):
     async def _get_connection_params(
         cls, conninfo: str, **kwargs: Any
     ) -> Dict[str, Any]:
-        """Manipulate connection parameters before connecting."""
+        """Manipulate connection parameters before connecting.
+
+        .. versionchanged:: 3.1
+            Unlike the sync counterpart, perform non-blocking address
+            resolution and populate the ``hostaddr`` connection parameter,
+            unless the user has provided one themselves. See
+            `~psycopg._dns.resolve_hostaddr_async()` for details.
+
+        """
         params = conninfo_to_dict(conninfo, **kwargs)
 
         # Make sure there is an usable connect_timeout