Added docs about pgconn_ptr, pgresult_ptr

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

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.
 

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: