Added connection.get_native_connection()

doc/src/connection.rst

@@ -768,7 +768,7 @@ The ``connection`` class
             support.
 
 
-    .. rubric:: Methods related to asynchronous support.
+    .. rubric:: Methods related to asynchronous support
 
     .. versionadded:: 2.2.0
 
@@ -813,6 +813,20 @@ The ``connection`` class
 
         Return `!True` if the connection is executing an asynchronous operation.
 
+    .. rubric:: Interoperation with other C API modules
+
+    .. method:: get_native_connection()
+
+        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.
+
+        .. seealso:: Python C API `Capsules`__  docs.
+
+            .. __: https://docs.python.org/3.1/c-api/capsule.html
+
+        .. versionadded:: 2.8
+
 
 .. testcode::
     :hide:

psycopg/connection_type.c

@@ -822,17 +822,17 @@ psyco_conn_deferrable_set(connectionObject *self, PyObject *pyvalue)
     return 0;
 }
 
-/* _raw_pgconn - expose PGconn* as a Python capsule */
+/* psyco_get_native_connection - expose PGconn* as a Python capsule */
 
-#define psyco_conn__raw_pgconn_doc \
+#define psyco_get_native_connection_doc \
-"Return the internal PGconn* as a Python Capsule."
+"get_native_connection() -- Return the internal PGconn* as a Python Capsule."
 
 static PyObject *
-psyco_conn__raw_pgconn_get(connectionObject *self)
+psyco_get_native_connection(connectionObject *self)
 {
     EXC_IF_CONN_CLOSED(self);
 
-    return PyCapsule_New(self->pgconn, "psycopg2.connection._raw_pgconn", NULL);
+    return PyCapsule_New(self->pgconn, "psycopg2.connection.native_connection", NULL);
 }
 
 
@@ -1190,6 +1190,8 @@ static struct PyMethodDef connectionObject_methods[] = {
      METH_NOARGS, psyco_conn_isexecuting_doc},
     {"cancel", (PyCFunction)psyco_conn_cancel,
      METH_NOARGS, psyco_conn_cancel_doc},
+    {"get_native_connection", (PyCFunction)psyco_get_native_connection,
+     METH_NOARGS, psyco_get_native_connection_doc},
     {NULL}
 };
 
@@ -1256,10 +1258,6 @@ static struct PyGetSetDef connectionObject_getsets[] = {
         (getter)psyco_conn_deferrable_get,
         (setter)psyco_conn_deferrable_set,
         psyco_conn_deferrable_doc },
-    { "_raw_pgconn",
-        (getter)psyco_conn__raw_pgconn_get,
-        NULL,
-        psyco_conn__raw_pgconn_doc },
     {NULL}
 };
 #undef EXCEPTION_GETTER

tests/test_connection.py

@@ -340,6 +340,11 @@ class ConnectionTests(ConnectingTestCase):
         self.assert_(c.closed, "connection failed so it must be closed")
         self.assert_('foobar' not in c.dsn, "password was not obscured")
 
+    def test_get_native_connection(self):
+        conn = self.connect()
+        capsule = conn.get_native_connection()
+        # we can't do anything else in Python
+        self.assertIsNotNone(capsule)
 
 class ParseDsnTestCase(ConnectingTestCase):
     def test_parse_dsn(self):