docs: document PGconn's tracing methods

diff --git a/docs/api/pq.rst b/docs/api/pq.rst
index d70071e05ca9b7e81eb1e4ad49a226132d8627a0..3d9c033fc0d36a13b0a01ca29b3d9a32c3249b97 100644 (file)
--- a/docs/api/pq.rst
+++ b/docs/api/pq.rst
@@ -99,6 +99,33 @@ Objects wrapping libpq structures and functions
            >>> encrypted = conn.pgconn.encrypt_password(password.encode(enc), rolename.encode(enc))
            b'SCRAM-SHA-256$4096:...
 
+    .. automethod:: trace
+    .. automethod:: set_trace_flags
+    .. automethod:: untrace
+
+    .. code:: python
+
+        >>> conn.pgconn.trace(sys.stderr.fileno())
+        >>> conn.pgconn.set_trace_flags(pq.Trace.SUPPRESS_TIMESTAMPS | pq.Trace.REGRESS_MODE)
+        >>> conn.execute("select now()")
+        F      13      Parse    "" "BEGIN" 0
+        F      14      Bind     "" "" 0 0 1 0
+        F      6       Describe         P ""
+        F      9       Execute  "" 0
+        F      4       Sync
+        B      4       ParseComplete
+        B      4       BindComplete
+        B      4       NoData
+        B      10      CommandComplete  "BEGIN"
+        B      5       ReadyForQuery    T
+        F      17      Query    "select now()"
+        B      28      RowDescription   1 "now" NNNN 0 NNNN 8 -1 0
+        B      39      DataRow  1 29 '2022-09-14 14:12:16.648035+02'
+        B      13      CommandComplete  "SELECT 1"
+        B      5       ReadyForQuery    T
+        <psycopg.Cursor [TUPLES_OK] [INTRANS] (database=postgres) at 0x7f18a18ba040>
+        >>> conn.pgconn.untrace()
+
 
 .. autoclass:: PGresult()
 
@@ -184,3 +211,8 @@ Enumerations
     :members:
 
     .. seealso:: :pq:`PQpingParams` for a description of these values.
+
+.. autoclass:: Trace
+    :members:
+
+    .. seealso:: :pq:`PQsetTraceFlags` for a description of these values.

diff --git a/psycopg/psycopg/pq/pq_ctypes.py b/psycopg/psycopg/pq/pq_ctypes.py
index f61ba3f736420434a7c757c01ff019b380fd2fbd..2bb929a27337a40afcda154575221a7142a8ef34 100644 (file)
--- a/psycopg/psycopg/pq/pq_ctypes.py
+++ b/psycopg/psycopg/pq/pq_ctypes.py
@@ -598,15 +598,32 @@ class PGconn:
             return nbytes, memoryview(b"")
 
     def trace(self, fileno: int) -> None:
+        """
+        Enable tracing of the client/server communication to a file stream.
+
+        See :pq:`PQtrace` for details.
+        """
         if sys.platform != "linux":
             raise e.NotSupportedError("currently only supported on Linux")
         stream = impl.fdopen(fileno, b"w")
         impl.PQtrace(self._pgconn_ptr, stream)
 
     def set_trace_flags(self, flags: Trace) -> None:
+        """
+        Configure tracing behavior of client/server communication.
+
+        :param flags: operating mode of tracing.
+
+        See :pq:`PQsetTraceFlags` for details.
+        """
         impl.PQsetTraceFlags(self._pgconn_ptr, flags)
 
     def untrace(self) -> None:
+        """
+        Disable tracing, previously enabled through `trace()`.
+
+        See :pq:`PQuntrace` for details.
+        """
         impl.PQuntrace(self._pgconn_ptr)
 
     def encrypt_password(