From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 18 Jul 2022 07:27:22 +0000 (+0100)
Subject: docs: move documentation from _dns module docstrings to docs
X-Git-Tag: 3.1~45^2~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a72087e85d3213632c5b7efde0250eba275c4595;p=thirdparty%2Fpsycopg.git

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 2c0904e85..d12de3ae2 100644
--- 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 ef8574ed7..1e146ba21 100644
--- 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)