docs: move documentation from _dns module docstrings to docs

Allow to build the _dns documentation without importing the module,
which requires external dependencies.

diff --git a/docs/api/dns.rst b/docs/api/dns.rst
index 2c0904e854f7a51206e5df3f35f74acbc03114e1..d12de3ae24937c8f582615c2f27ea464cee9c85b 100644 (file)
--- a/docs/api/dns.rst
+++ b/docs/api/dns.rst
@@ -23,7 +23,25 @@ server before performing a connection.
     .. _dnspython: https://dnspython.readthedocs.io/
 
 
-.. autofunction:: resolve_srv
+.. function:: resolve_srv
+
+    Apply SRV DNS lookup as defined in :RFC:`2782`.
+
+    :param params: The input parameters, for instance as returned by
+        `~psycopg.conninfo.conninfo_to_dict()`.
+    :return: An updated list of connection parameters.
+
+    For every host defined in the ``params["host"]`` list (comma-separated),
+    perform SRV lookup if the host is in the form ``_Service._Proto.Target``.
+    If lookup is successful, return a params dict with hosts and ports replaced
+    with the looked-up entries.
+
+    Raise `~psycopg.OperationalError` if no lookup is successful and no host
+    (looked up or unchanged) could be returned.
+
+    In addition to the rules defined by RFC 2782 about the host name pattern,
+    perform SRV lookup also if the the port is the string ``SRV`` (case
+    insensitive).
 
    .. warning::
        This is an experimental functionality.
@@ -46,7 +64,9 @@ server before performing a connection.
            cnn = SrvCognizantConnection.connect("host=_postgres._tcp.db.psycopg.org")
 
 
-.. autofunction:: resolve_srv_async
+.. function:: resolve_srv_async
+
+    Async equivalent of `resolve_srv()`.
 
 
 .. automethod:: psycopg.Connection._get_connection_params
@@ -71,7 +91,36 @@ server before performing a connection.
        This is an experimental method.
 
 
-.. autofunction:: resolve_hostaddr_async
+.. function:: resolve_hostaddr_async
+
+    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()`.
+
+    If a ``host`` param is present but not ``hostname``, resolve the host
+    addresses dynamically.
+
+    The function may change the input ``host``, ``hostname``, ``port`` to allow
+    connecting without further DNS lookups, eventually removing hosts that are
+    not resolved, keeping the lists of hosts and ports consistent.
+
+    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.
+
+    .. __: https://www.postgresql.org/docs/current/libpq-connect.html
+           #LIBPQ-PARAMKEYWORDS
+
+    .. warning::
+        Before psycopg 3.1, this function doesn't handle the ``/etc/hosts`` file.
 
    .. note::
        Starting from psycopg 3.1, a similar operation is performed

diff --git a/psycopg/psycopg/_dns.py b/psycopg/psycopg/_dns.py
index ef8574ed780d0e7720b1ef7262641ae4ad34052b..1e146ba216c7bad4dac15f8138af5f3ddbdb7306 100644 (file)
--- a/psycopg/psycopg/_dns.py
+++ b/psycopg/psycopg/_dns.py
@@ -43,28 +43,6 @@ async def resolve_hostaddr_async(params: Dict[str, Any]) -> Dict[str, Any]:
         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()`.
-
-    If a ``host`` param is present but not ``hostname``, resolve the host
-    addresses dynamically.
-
-    The function may change the input ``host``, ``hostname``, ``port`` to allow
-    connecting without further DNS lookups, eventually removing hosts that are
-    not resolved, keeping the lists of hosts and ports consistent.
-
-    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.
-
-    .. __: https://www.postgresql.org/docs/current/libpq-connect.html
-           #LIBPQ-PARAMKEYWORDS
-
-    .. warning::
-        Before psycopg 3.1, this function doesn't handle the ``/etc/hosts`` file.
     """
     warnings.warn(
         "from psycopg 3.1, resolve_hostaddr_async() is not needed anymore",
@@ -74,24 +52,7 @@ async def resolve_hostaddr_async(params: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def resolve_srv(params: Dict[str, Any]) -> Dict[str, Any]:
-    """Apply SRV DNS lookup as defined in :RFC:`2782`.
-
-    :param params: The input parameters, for instance as returned by
-        `~psycopg.conninfo.conninfo_to_dict()`.
-    :return: An updated list of connection parameters.
-
-    For every host defined in the ``params["host"]`` list (comma-separated),
-    perform SRV lookup if the host is in the form ``_Service._Proto.Target``.
-    If lookup is successful, return a params dict with hosts and ports replaced
-    with the looked-up entries.
-
-    Raise `~psycopg.OperationalError` if no lookup is successful and no host
-    (looked up or unchanged) could be returned.
-
-    In addition to the rules defined by RFC 2782 about the host name pattern,
-    perform SRV lookup also if the the port is the string ``SRV`` (case
-    insensitive).
-    """
+    """Apply SRV DNS lookup as defined in :RFC:`2782`."""
     return Rfc2782Resolver().resolve(params)