Merge pull request #805 from fogzot/feature-expose-pgconn

Feature expose pgconn

.gitignore

@@ -15,5 +15,6 @@ env
 env?
 .idea
 .tox
+.vscode/
 /rel
 /wheels

doc/Makefile

@@ -10,7 +10,8 @@ check: doctest
 PYTHON := python$(PYTHON_VERSION)
 PYTHON_VERSION ?= $(shell $(PYTHON) -c 'import sys; print ("%d.%d" % sys.version_info[:2])')
 
-SPHOPTS=PYTHONPATH=$$(pwd)/../build/lib.$(PYTHON_VERSION)/ SPHINXBUILD=$$(pwd)/env/bin/sphinx-build
+SPHINXBUILD ?= $$(pwd)/env/bin/sphinx-build
+SPHOPTS = PYTHONPATH=$$(pwd)/../build/lib.$(PYTHON_VERSION)/ SPHINXBUILD=$(SPHINXBUILD)
 
 html:
 	$(MAKE) PYTHON=$(PYTHON) -C .. package

doc/src/connection.rst

@@ -693,8 +693,7 @@ The ``connection`` class
             support.
 
 
-
+    .. rubric:: Methods related to asynchronous support
-    .. rubric:: Methods related to asynchronous support.
 
     .. versionadded:: 2.2.0
 
@@ -739,6 +738,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
+
 
 
     .. rubric:: informative methods of the native connection

psycopg/connection_type.c

@@ -825,6 +825,19 @@ psyco_conn_deferrable_set(connectionObject *self, PyObject *pyvalue)
     return 0;
 }
 
+/* psyco_get_native_connection - expose PGconn* as a Python capsule */
+
+#define psyco_get_native_connection_doc \
+"get_native_connection() -- Return the internal PGconn* as a Python Capsule."
+
+static PyObject *
+psyco_get_native_connection(connectionObject *self)
+{
+    EXC_IF_CONN_CLOSED(self);
+
+    return PyCapsule_New(self->pgconn, "psycopg2.connection.native_connection", NULL);
+}
+
 
 /* set_client_encoding method - set client encoding */
 
@@ -1194,6 +1207,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}
 };
 

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):