What is the return value of Connection.ping() in cx_oracle?

Question

I've just installed a python package：cx_oracle. From the cx_oracle document I found a method: Connection.ping(), which is described as "Ping the server which can be used to test if the connection is still active.".

But the document doesn't mentioned what is the return value of ping().

I wrote some code to do a test:

#!/usr/bin/env python3
import cx_Oracle
conn = cx_Oracle.connect("...")
print(conn.ping()) # display：None
conn.close()
print(conn.ping()) # raise exception: cx_Oracle.InterfaceError: not connected

From the test result, I found the ping() will return None if the connection is OK or raise an exception: cx_Oracle.InterfaceError: not connected after the connection is closed.

Is there any other possible return values? Why not just return True or False?

Answer 1

Thanks to Ben's answer, given a connectionObject from the cx_Oracle library, this should at least incapsulate what you might want.

def isOpen(connectionObject):
    try:
        return connectionObject.ping() is None
    except:
        return False

Answer 2

The cx_Oracle documentation states that this is:

This method is an extension to the DB API definition and is only available in Oracle 10g R2 and higher.

However, this method isn't documented in PEP 249 - the current Python Database API specification in either the connection methods or optional extensions (or anywhere else for that matter).

The MySQL implementation of PEP 249 also has this method; the documentation states that:

When the connection is not available, an InterfaceError is raised. Use the is_connected() method to check the connection without raising an error.

Raises InterfaceError on errors.

As this is identical to the cx_Oracle behaviour I would assume that this is the answer to your question and what you've determined the behaviour to be is correct:

• There is no return if the connection is active
• An InterfaceError is raised if the connection is not active

If we look at the code for .ping(), it confirms that this is the manner in which the method has been implemented:

static PyObject *Connection_Ping(
    udt_Connection *self,               // connection
    PyObject* args)                     // arguments
{
    sword status;

    if (Connection_IsConnected(self) < 0)
        return NULL;
    status = OCIPing(self->handle, self->environment->errorHandle,
            OCI_DEFAULT);
    if (Environment_CheckForError(self->environment, status,
            "Connection_Ping()") < 0)
        return NULL;
    Py_INCREF(Py_None);
    return Py_None;
}