4. Code Injection Semantics¶

4.3.1. Noteworthy Cases¶

The type system description system gives the binding developer a lot of flexibility, which is power, which comes with responsibility. Some modifications to the wrapped API will not be complete without some code injection.

4.4.1. On The Native Side¶

Notice that this is only used when there is a C++ wrapper, i.e. the wrapped class is polymorphic.

int InjectCodeWrapper::virtualMethod(int arg)
{
    PyObject* method = BindingManager::instance().getOverride(this, "virtualMethod");
    if (!py_override)
        return this->InjectCode::virtualMethod(arg);

    (... here C++ arguments are converted to Python ...)

    // INJECT-CODE: <modify-function><inject-code class="native" position="beginning">
    // Uses: pre method call custom code, modify the argument before the
    // Python call.

    (... Python method call goes in here ...)

    // INJECT-CODE: <modify-function><inject-code class="native" position="end">
    // Uses: post method call custom code, modify the result before delivering
    // it to C++ caller.

    (... Python method and argument tuple are dereferenced here ...)

    return Shiboken::Converter<int>::toCpp(method_result);
}

4.4.2. On The Target Side¶

All the overloads of a method from C++ are gathered together on a single Python method that uses an overload decisor to call the correct C++ method based on the arguments passed by the Python call. Each overloaded method signature has its own beginning and end code injections.

static PyObject*
PyInjectCode_overloadedMethod(PyObject* self, PyObject* arg)
{
    PyObject* py_result = 0;
    if (PyFloat_Check(arg)) {
        double cpp_arg0 = Shiboken::Converter<double >::toCpp(arg);

        // INJECT-CODE: <modify-function><inject-code class="target" position="beginning">
        // Uses: pre method call custom code.

        py_result = Shiboken::Converter<double >::toPython(
            PyInjectCode_cptr(self)->InjectCode::overloadedMethod(cpp_arg0)
        );

        // INJECT-CODE: <modify-function><inject-code class="target" position="end">
        // Uses: post method call custom code.

    } else if (PyNumber_Check(arg)) {
        (... other overload calling code ...)
    } else goto PyInjectCode_overloadedMethod_TypeError;

    if (PyErr_Occurred() || !py_result)
        return 0;

    return py_result;

    PyInjectCode_overloadedMethod_TypeError:
        PyErr_SetString(PyExc_TypeError, "'overloadedMethod()' called with wrong parameters.");
        return 0;
}

4.5.1. On The Native Side¶

Those injections go in the body of the CLASSNAME_wrapper.cpp file for the wrapped class.

// Start of ``CLASSNAME_wrapper.cpp``
#define protected public
// default includes
#include <shiboken.h>
(...)
#include "injectcode_wrapper.h"
using namespace Shiboken;

// INJECT-CODE: <value/object-type><inject-code class="native" position="beginning">
// Uses: prototype declarations

(... C++ wrapper virtual methods, if any ...)

(... Python wrapper code ...)

PyAPI_FUNC(void)
init_injectcode(PyObject *module)
{
    (...)
}

(...)

// INJECT-CODE: <value/object-type><inject-code class="native" position="end">
// Uses: definition of functions prototyped at ``native/beginning``.

// End of ``CLASSNAME_wrapper.cpp``

4.5.2. On The Target Side¶

Code injections to the class Python initialization function.

// Start of ``CLASSNAME_wrapper.cpp``

(...)

PyAPI_FUNC(void)
init_injectcode(PyObject *module)
{
    // INJECT-CODE: <value/object-type><inject-code class="target" position="beginning">
    // Uses: Alter something in the PyInjectCode_Type (tp_flags value for example)
    // before registering it.

    if (PyType_Ready(&PyInjectCode_Type) < 0)
        return;

    Py_INCREF(&PyInjectCode_Type);
    PyModule_AddObject(module, "InjectCode",
        ((PyObject*)&PyInjectCode_Type));

    // INJECT-CODE: <value/object-type><inject-code class="target" position="end">
    // Uses: do something right after the class is registered, like set some static
    // variable injected on this same file elsewhere.
}

(...)

// End of ``CLASSNAME_wrapper.cpp``

4.6.1. On The Native Side¶

This works exactly as the class wrapper code injections On The Native Side.

4.6.2. On The Target Side¶

This is very similar to class wrapper code injections On The Target Side. Notice that the inject code at target/end is inserted before the check for errors to prevent bad custom code to pass unnoticed.

// Start of ``MODULENAME_module_wrapper.cpp``

(...)
initMODULENAME()
{
    // INJECT-CODE: <typesystem><inject-code class="target" position="beginning">
    // Uses: do something before the module is created.

    PyObject* module = Py_InitModule("MODULENAME", MODULENAME_methods);

    (... initialization of wrapped classes, namespaces, functions and enums ...)

    // INJECT-CODE: <typesystem><inject-code class="target" position="end">
    // Uses: do something after the module is registered and initialized.

    if (PyErr_Occurred())
        Py_FatalError("can't initialize module sample");
}

(...)

// Start of ``MODULENAME_module_wrapper.cpp``