Added docs about pgconn_ptr, pgresult_ptrlibpq-ptrs

3 files changed, 38 insertions, 2 deletions

diff --git a/NEWS b/NEWS
index 984d531..adc6685 100644
--- a/NEWS
+++ b/NEWS
@@ -17,7 +17,9 @@ New features:
 - Added `connection.info` object to retrieve various PostgreSQL connection
   information (:ticket:`#726`).
 - Added `~connection.get_native_connection()` to expose the raw ``PGconn``
-  structure (:ticket:`#782`).
+  structure to C extensions via Capsule (:ticket:`#782`).
+- Added `~connection.pgconn_ptr` and `~cursor.pgresult_ptr` to expose raw
+  C structures to Python and interact with libpq via ctypes (:ticket:`#782`).
 - `~psycopg2.sql.Identifier` can represent qualified names in SQL composition
   (:ticket:`#732`).
 - Added *fetch* parameter to `~psycopg2.extras.execute_values()` function
diff --git a/doc/src/connection.rst b/doc/src/connection.rst
index 179b7ba..9c04e83 100644
--- a/doc/src/connection.rst
+++ b/doc/src/connection.rst
@@ -738,11 +738,27 @@ The ``connection`` class
 
         Return `!True` if the connection is executing an asynchronous operation.
 
+
     .. rubric:: Interoperation with other C API modules
 
+    .. attribute:: pgconn_ptr
+
+        Return the internal `!PGconn*` as integer. Useful to pass the libpq
+        raw connection structure to C functions, e.g. via `ctypes`::
+
+            >>> import ctypes
+            >>> libpq = ctypes.pydll.LoadLibrary(ctypes.util.find_library('pq'))
+            >>> libpq.PQserverVersion.argtypes = [ctypes.c_void_p]
+            >>> libpq.PQserverVersion.restype = ctypes.c_int
+            >>> libpq.PQserverVersion(conn.pgconn_ptr)
+            90611
+
+        .. versionadded:: 2.8
+
+
     .. method:: get_native_connection()
 
-        Return the internal `PGconn*` wrapped in a PyCapsule object. This is
+        Return the internal `!PGconn*` wrapped in a PyCapsule object. This is
         only useful for passing the `libpq` raw connection associated to this
         connection object to other C-level modules that may have a use for it.
 
diff --git a/doc/src/cursor.rst b/doc/src/cursor.rst
index 1d7098f..c6b04cf 100644
--- a/doc/src/cursor.rst
+++ b/doc/src/cursor.rst
@@ -632,6 +632,24 @@ The ``cursor`` class
             using Unicode data instead of bytes.
 
 
+    .. rubric:: Interoperation with other C API modules
+
+    .. attribute:: pgresult_ptr
+
+        Return the cursor's internal `!PGresult*` as integer. Useful to pass
+        the libpq raw result structure to C functions, e.g. via `ctypes`::
+
+            >>> import ctypes
+            >>> libpq = ctypes.pydll.LoadLibrary(ctypes.util.find_library('pq'))
+            >>> libpq.PQcmdStatus.argtypes = [ctypes.c_void_p]
+            >>> libpq.PQcmdStatus.restype = ctypes.c_char_p
+
+            >>> curs.execute("select 'x'")
+            >>> libpq.PQcmdStatus(curs.pgresult_ptr)
+            b'SELECT 1'
+
+        .. versionadded:: 2.8
+
 .. testcode::
     :hide: