docs: add documentation about async DNS resolution

Close #259.

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index c3a91561eae2119d1c5252b21829541a0b3ed906..b1858fb1dda8b2f21c55bcc12bc22d60cf2d8278 100644 (file)
--- 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 84e07b9268073775ca8271de48de1b417cf20570..2c0904e854f7a51206e5df3f35f74acbc03114e1 100644 (file)
--- 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 3494f6171e7c6d13b1002868712f7062d5f69ae1..e5f75ef92134f735b9be2f40496142e8b11d39c1 100644 (file)
--- 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 cab164012bb7bd59833df89d06e506596dee8050..e7e5ddb59d30d7646541a05d2f9f0653b20b8159 100644 (file)
--- 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 8c6571d0c4aa128a651118eb844ec7ef8f9bc36e..1545667b74a0697c64cac1f721ef884942a5e5da 100644 (file)
--- 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