From 725c14d90bffbf2f95f6e66e245c839dece46c47 Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 12 Apr 2021 18:30:40 +0100
Subject: [PATCH] Add ConnectionInfo docs

---
 docs/api/connections.rst        | 23 ++++++++++++++++++++---
 psycopg3/psycopg3/__init__.py   |  1 +
 psycopg3/psycopg3/connection.py |  1 +
 psycopg3/psycopg3/conninfo.py   | 19 +++++++++++++++++++
 4 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index 32ccd45de..7a0612661 100644
--- 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 ed687e548..642c6011c 100644
--- 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 f927fb0b0..7f2b5b17a 100644
--- 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 970d37cb4..292846e89 100644
--- 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
 
-- 
2.47.2