From: Daniele Varrazzo Date: Sun, 29 Aug 2021 16:31:40 +0000 (+0200) Subject: Add _dns module docs X-Git-Tag: 3.0.beta1~5^2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a177b4920198b3b479b8de98b41bdb655e2278fa;p=thirdparty%2Fpsycopg.git Add _dns module docs --- diff --git a/docs/api/_dns.rst b/docs/api/_dns.rst new file mode 100644 index 000000000..14c1e4026 --- /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 e605c0b8b..ec425fd4a 100644 --- 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 4c7798830..f4ac6ffe6 100644 --- 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 ee6b3981a..5999f6ac0 100644 --- 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 d14e19431..38c032ff1 100644 --- 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 cd3a1da5b..2f689a169 100644 --- 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",