From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 22 Apr 2021 23:51:18 +0000 (+0100)
Subject: Further ConnectionInfo docs improvements
X-Git-Tag: 3.0.dev0~66^2~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ae32cd40433901de5b8ffa1f1b3291943b2ef3dd;p=thirdparty%2Fpsycopg.git

Further ConnectionInfo docs improvements
---

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index 8b19c410d..566fbd069 100644
--- a/docs/api/connections.rst
+++ b/docs/api/connections.rst
@@ -254,10 +254,34 @@ Connection support objects
     The object is usually returned by `Connection.info`.
 
     .. autoattribute:: status
+
+        The status can be one of a number of values. However, only two of
+        these are seen outside of an asynchronous connection procedure:
+        `~pq.ConnStatus.OK` and `~pq.ConnStatus.BAD`. A good connection to the
+        database has the status `!OK`. Ordinarily, an `!OK` status will remain
+        so until `Connection.close()`, but a communications failure might
+        result in the status changing to `!BAD` prematurely.
+
     .. autoattribute:: transaction_status
+
+        The status can be `~pq.TransactionStatus.IDLE` (currently idle),
+        `~pq.TransactionStatus.ACTIVE` (a command is in progress),
+        `~pq.TransactionStatus.INTRANS` (idle, in a valid transaction block),
+        or `~pq.TransactionStatus.INERROR` (idle, in a failed transaction
+        block). `~pq.TransactionStatus.UNKNOWN` is reported if the connection
+        is bad. `!ACTIVE` is reported only when a query has been sent to the
+        server and not yet completed.
+
     .. autoattribute:: server_version
     .. automethod:: get_parameters
     .. autoattribute:: host
+
+        This can be a host name, an IP address, or a directory path if the
+        connection is via Unix socket. (The path case can be distinguished
+        because it will always be an absolute path, beginning with ``/``.)
+
+    .. autoattribute:: hostaddr
+
     .. autoattribute:: port
     .. autoattribute:: dbname
     .. autoattribute:: user
diff --git a/psycopg3/psycopg3/conninfo.py b/psycopg3/psycopg3/conninfo.py
index 34e402307..94d6149e4 100644
--- a/psycopg3/psycopg3/conninfo.py
+++ b/psycopg3/psycopg3/conninfo.py
@@ -103,17 +103,17 @@ class ConnectionInfo:
 
     @property
     def host(self) -> str:
-        """The host name of the database. See :pq:`PQhost`."""
+        """The server host name of the active connection. See :pq:`PQhost`."""
         return self._get_pgconn_attr("host")
 
     @property
     def hostaddr(self) -> str:
-        """The server ip address of the connection. See :pq:`PQhostaddr`."""
+        """The server IP address of the connection. See :pq:`PQhostaddr`."""
         return self._get_pgconn_attr("hostaddr")
 
     @property
     def port(self) -> int:
-        """The port of the database connection. See :pq:`PQport`."""
+        """The port of the active connection. See :pq:`PQport`."""
         return int(self._get_pgconn_attr("port"))
 
     @property
@@ -123,18 +123,19 @@ class ConnectionInfo:
 
     @property
     def user(self) -> str:
-        """The user of the database connection. See :pq:`PQuser`."""
+        """The user name of the connection. See :pq:`PQuser`."""
         return self._get_pgconn_attr("user")
 
     @property
     def password(self) -> str:
-        """The password of the database connection. See :pq:`PQpass`."""
+        """The password of the connection. See :pq:`PQpass`."""
         return self._get_pgconn_attr("password")
 
     @property
     def options(self) -> str:
         """
-        The options parameter of the database connection. See :pq:`PQoptions`.
+        The command-line options passed in the connection request.
+        See :pq:`PQoptions`.
         """
         return self._get_pgconn_attr("options")
 
@@ -167,13 +168,14 @@ class ConnectionInfo:
 
     @property
     def status(self) -> pq.ConnStatus:
-        """`pq.ConnStatus` enum representing the state of the connection."""
+        """The status of the connection. See :pq:`PQstatus`."""
         return pq.ConnStatus(self.pgconn.status)
 
     @property
     def transaction_status(self) -> pq.TransactionStatus:
         """
-        `pq.TransactionStatus` enum representing the state of the transaction.
+        The current in-transaction status of the server.
+        See :pq:`PQtransactionStatus`.
         """
         return pq.TransactionStatus(self.pgconn.transaction_status)
 
@@ -201,7 +203,9 @@ class ConnectionInfo:
 
     @property
     def protocol_version(self) -> int:
-        """The frontend/backend protocol currently used."""
+        """
+        The frontend/backend protocol currently used. See :pq:`PQprotocolVersion`.
+        """
         return self.pgconn.protocol_version
 
     def _get_pgconn_attr(self, name: str) -> str: