Add ConnectionInfo docs

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index 32ccd45deeca46cdc222423b173acde43390262b..7a06126613f3b194a7114f7590812b5e282d16b9 100644 (file)
--- a/docs/api/connections.rst
+++ b/docs/api/connections.rst
@@ -159,9 +159,7 @@ The `!Connection` class
             .. __: https://www.postgresql.org/docs/current/multibyte.html
 
 
-    .. attribute:: info
-
-        TODO
+    .. autoattribute:: info
 
     .. automethod:: fileno
 
@@ -251,6 +249,25 @@ Connection support objects
     The object is usually returned by `Connection.notifies()`.
 
 
+.. autoclass:: ConnectionInfo()
+
+    The object is usually returned by `Connection.info`.
+
+    .. autoproperty:: host
+    .. autoproperty:: port
+    .. autoproperty:: dbname
+    .. autoproperty:: user
+    .. autoproperty:: password
+    .. autoproperty:: options
+    .. autoproperty:: status
+    .. autoproperty:: transaction_status
+    .. automethod:: get_parameters
+    .. automethod:: parameter_status
+
+        Example of parameters are ``server_version``,
+        ``standard_conforming_string``... See :pq:`PQparameterStatus()` for
+        all the available parameters.
+
 .. rubric:: Objects involved in :ref:`transactions`
 
 .. autoclass:: Transaction()

diff --git a/psycopg3/psycopg3/__init__.py b/psycopg3/psycopg3/__init__.py
index ed687e5488424f30cc7869b5f302e77f6aed8279..642c6011c76b17c77ece5f1eea06f5a6fea9616d 100644 (file)
--- a/psycopg3/psycopg3/__init__.py
+++ b/psycopg3/psycopg3/__init__.py
@@ -15,6 +15,7 @@ from .errors import Warning, Error, InterfaceError, DatabaseError
 from .errors import DataError, OperationalError, IntegrityError
 from .errors import InternalError, ProgrammingError, NotSupportedError
 from ._column import Column
+from .conninfo import ConnectionInfo
 from .connection import BaseConnection, AsyncConnection, Connection, Notify
 from .transaction import Rollback, Transaction, AsyncTransaction
 from .server_cursor import AsyncServerCursor, ServerCursor

diff --git a/psycopg3/psycopg3/connection.py b/psycopg3/psycopg3/connection.py
index f927fb0b04ed2fef451ea473eb700c3bc4697761..7f2b5b17acf27d165851948c11b1261b98632789 100644 (file)
--- a/psycopg3/psycopg3/connection.py
+++ b/psycopg3/psycopg3/connection.py
@@ -217,6 +217,7 @@ class BaseConnection(AdaptContext):
 
     @property
     def info(self) -> ConnectionInfo:
+        """A `ConnectionInfo` attribute to inspect connection properties."""
         return ConnectionInfo(self.pgconn)
 
     @property

diff --git a/psycopg3/psycopg3/conninfo.py b/psycopg3/psycopg3/conninfo.py
index 970d37cb403b3e4a6e8095c0d80d2599240d4e68..292846e897cfd3ddb38be08bf640918c6a37cd22 100644 (file)
--- a/psycopg3/psycopg3/conninfo.py
+++ b/psycopg3/psycopg3/conninfo.py
@@ -94,31 +94,41 @@ def _param_escape(s: str) -> str:
 
 
 class ConnectionInfo:
+    """Allow access to information about the connection."""
+
+    __module__ = "psycopg3"
+
     def __init__(self, pgconn: pq.proto.PGconn):
         self.pgconn = pgconn
 
     @property
     def host(self) -> str:
+        """The host name of the database."""
         return self._get_pgconn_attr("host")
 
     @property
     def port(self) -> int:
+        """The port of the database connection."""
         return int(self._get_pgconn_attr("port"))
 
     @property
     def dbname(self) -> str:
+        """The name of the connected database."""
         return self._get_pgconn_attr("db")
 
     @property
     def user(self) -> str:
+        """The user of the database connection."""
         return self._get_pgconn_attr("user")
 
     @property
     def password(self) -> str:
+        """The password of the database connection."""
         return self._get_pgconn_attr("password")
 
     @property
     def options(self) -> str:
+        """The options parameter of the database connection."""
         return self._get_pgconn_attr("options")
 
     def get_parameters(self) -> Dict[str, str]:
@@ -150,13 +160,22 @@ class ConnectionInfo:
 
     @property
     def status(self) -> pq.ConnStatus:
+        """`pq.ConnStatus` enum representing the state of the connection."""
         return pq.ConnStatus(self.pgconn.status)
 
     @property
     def transaction_status(self) -> pq.TransactionStatus:
+        """
+        `pq.TransactionStatus` enum representing the state of the transaction.
+        """
         return pq.TransactionStatus(self.pgconn.transaction_status)
 
     def parameter_status(self, param_name: str) -> Optional[str]:
+        """
+        Return a parameter setting of the connection.
+
+        Return `None` is the parameter is unknown.
+        """
         res = self.pgconn.parameter_status(param_name.encode(self._pyenc))
         return res.decode(self._pyenc) if res is not None else None