diff --git a/doc/src/connection.rst b/doc/src/connection.rst index 2910f301..545cd727 100644 --- a/doc/src/connection.rst +++ b/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: diff --git a/psycopg/connection_type.c b/psycopg/connection_type.c index 724cf853..635aa306 100644 --- a/psycopg/connection_type.c +++ b/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 \ -"Return the internal 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_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 diff --git a/tests/test_connection.py b/tests/test_connection.py index 1342f9f8..3b8f7750 100755 --- a/tests/test_connection.py +++ b/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):