From: Denis Laxalde <denis.laxalde@dalibo.com>
Date: Wed, 14 Sep 2022 12:20:05 +0000 (+0200)
Subject: docs: document PGconn's tracing methods
X-Git-Tag: 3.1.2~6^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F373%2Fhead;p=thirdparty%2Fpsycopg.git

docs: document PGconn's tracing methods
---

diff --git a/docs/api/pq.rst b/docs/api/pq.rst
index d70071e05..3d9c033fc 100644
--- 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 f61ba3f73..2bb929a27 100644
--- 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(