# cppmethod: wrap class methods and constructors

Wrap C++ class methods and constructods.

class pybindgen.cppmethod.CppConstructor(parameters, unblock_threads=None, visibility='public', deprecated=False, throw=())

  Bases: `pybindgen.typehandlers.base.ForwardWrapperBase`

  Class that generates a wrapper to a C++ class constructor. Such wrapper is used as the python class __init__ method.

  Parameters

    - parameters – the constructor parameters

    - deprecated – deprecation state for this API: False=Not deprecated; True=Deprecated; “message”=Deprecated, and deprecation warning contains the given message

    - throw (list of `pybindgen.cppexception.CppException`) – list of C++ exceptions that the constructor may throw

  add_custodian_and_ward(custodian, ward, postcall=None)

    Add a custodian/ward relationship to the constructor wrapper

    A custodian/ward relationship is one where one object (custodian) keeps a references to another object (ward), thus keeping it alive. When the custodian is destroyed, the reference to the ward is released, allowing the ward to be freed if no other reference to it is being kept by the user code. Please note that custodian/ward manages the lifecycle of Python wrappers, not the C/C++ objects referenced by the wrappers. In most cases, the wrapper owns the C/C++ object, and so the lifecycle of the C/C++ object is also managed by this. However, there are cases when a Python wrapper does not own the underlying C/C++ object, only references it.

    The custodian and ward objects are indicated by an integer with the following meaning:

    > - C{0}: the object being constructed (self)

    > - value > 0: the nth parameter of the function, starting at 1

    Parameters

      - custodian – number of the object that assumes the role of custodian

      - ward – number of the object that assumes the role of ward

      - postcall – if True, the relationship is added after the C function call, if False it is added before the call. If not given, the value False is assumed if the return value is not involved, else postcall=True is used.

  property class_

    Get the class wrapper object (CppClass)

  clone()

    Creates a semi-deep copy of this constructor wrapper. The returned constructor wrapper clone contains copies of all parameters, so they can be modified at will.

  generate(code_sink, wrapper_name=None, extra_wrapper_params=())

    Generates the wrapper code :param code_sink: a CodeSink instance that will receive the generated code :returns: the wrapper function name.

  generate_call(class_=None)

    virtual method implementation; do not call

  generate_docstring(name)
  get_class()

    Get the class wrapper object (CppClass)

  set_class(class_)

    Set the class wrapper object (CppClass)

class pybindgen.cppmethod.CppDummyMethod(method_name, return_value, parameters, *args, **kwargs)

  Bases: `pybindgen.cppmethod.CppMethod`

  A ‘dummy’ method; cannot be generated due to incomple or incorrect parameters, but is added to the class to model the missing method.

  Create an object the generates code to wrap a C++ class method.

  Parameters

    - return_value (L{ReturnValue}) – the method return value

    - method_name – name of the method

    - parameters (list of `pybindgen.typehandlers.base.Parameter`) – the method parameters

    - is_static – whether it is a static method

    - template_parameters (list of strings, each element a template parameter expression) – optional list of template parameters needed to invoke the method

    - is_virtual – whether the method is virtual (pure or not)

    - is_const – whether the method has a const modifier on it

    - unblock_threads – whether to release the Python GIL around the method call or not. If None or omitted, use global settings. Releasing the GIL has a small performance penalty, but is recommended if the method is expected to take considerable time to complete, because otherwise no other Python thread is allowed to run until the method completes.

    - is_pure_virtual – whether the method is defined as “pure virtual”, i.e. virtual method with no default implementation in the class being wrapped.

    - custom_name – alternate name to give to the method, in python side.

    - custom_template_method_name – (deprecated) same as parameter ‘custom_name’.

    - visibility (a string (allowed values are 'public', 'protected', 'private')) – visibility of the method within the C++ class

    - deprecated – deprecation state for this API: - False: Not deprecated - True: Deprecated - “message”: Deprecated, and deprecation warning contains the given message

    - throw (list of L{CppException}) – list of C++ exceptions that the function may throw

class pybindgen.cppmethod.CppFunctionAsConstructor(c_function_name, return_value, parameters, unblock_threads=None)

  Bases: `pybindgen.cppmethod.CppConstructor`

  Class that generates a wrapper to a C/C++ function that appears as a contructor.

  Parameters

    - c_function_name – name of the C/C++ function; FIXME: for now it is implied that this function returns a pointer to the a class instance with caller_owns_return=True semantics.

    - return_value (L{ReturnValue}) – function return value type

    - parameters (list of L{Parameter}) – the function/constructor parameters

  generate_call(class_=None)

    virtual method implementation; do not call

class pybindgen.cppmethod.CppMethod(method_name, return_value, parameters, is_static=False, template_parameters=(), is_virtual=None, is_const=False, unblock_threads=None, is_pure_virtual=False, custom_template_method_name=None, visibility='public', custom_name=None, deprecated=False, docstring=None, throw=())

  Bases: `pybindgen.typehandlers.base.ForwardWrapperBase`

  Class that generates a wrapper to a C++ class method

  Create an object the generates code to wrap a C++ class method.

  Parameters

    - return_value (L{ReturnValue}) – the method return value

    - method_name – name of the method

    - parameters (list of `pybindgen.typehandlers.base.Parameter`) – the method parameters

    - is_static – whether it is a static method

    - template_parameters (list of strings, each element a template parameter expression) – optional list of template parameters needed to invoke the method

    - is_virtual – whether the method is virtual (pure or not)

    - is_const – whether the method has a const modifier on it

    - unblock_threads – whether to release the Python GIL around the method call or not. If None or omitted, use global settings. Releasing the GIL has a small performance penalty, but is recommended if the method is expected to take considerable time to complete, because otherwise no other Python thread is allowed to run until the method completes.

    - is_pure_virtual – whether the method is defined as “pure virtual”, i.e. virtual method with no default implementation in the class being wrapped.

    - custom_name – alternate name to give to the method, in python side.

    - custom_template_method_name – (deprecated) same as parameter ‘custom_name’.

    - visibility (a string (allowed values are 'public', 'protected', 'private')) – visibility of the method within the C++ class

    - deprecated – deprecation state for this API: - False: Not deprecated - True: Deprecated - “message”: Deprecated, and deprecation warning contains the given message

    - throw (list of L{CppException}) – list of C++ exceptions that the function may throw

  add_custodian_and_ward(custodian, ward, postcall=None)

    Add a custodian/ward relationship to the method wrapper

    A custodian/ward relationship is one where one object (custodian) keeps a references to another object (ward), thus keeping it alive. When the custodian is destroyed, the reference to the ward is released, allowing the ward to be freed if no other reference to it is being kept by the user code. Please note that custodian/ward manages the lifecycle of Python wrappers, not the C/C++ objects referenced by the wrappers. In most cases, the wrapper owns the C/C++ object, and so the lifecycle of the C/C++ object is also managed by this. However, there are cases when a Python wrapper does not own the underlying C/C++ object, only references it.

    The custodian and ward objects are indicated by an integer with the following meaning:

    > - C{-1}: the return value of the function

    > - C{0}: the instance of the method (self)

    > - value > 0: the nth parameter of the function, starting at 1

    Parameters

      - custodian – number of the object that assumes the role of custodian

      - ward – number of the object that assumes the role of ward

      - postcall – if True, the relationship is added after the C function call, if False it is added before the call. If not given, the value False is assumed if the return value is not involved, else postcall=True is used.

  property class_

    get the class object this method belongs to

  clone()

    Creates a semi-deep copy of this method wrapper. The returned method wrapper clone contains copies of all parameters, so they can be modified at will.

  property custom_name
  generate(code_sink, wrapper_name=None, extra_wrapper_params=())

    Generates the wrapper code code_sink – a CodeSink instance that will receive the generated code method_name – actual name the method will get extra_wrapper_params – extra parameters the wrapper function should receive

    Returns the corresponding PyMethodDef entry string.

  generate_call(class_=None)

    virtual method implementation; do not call

  generate_docstring(name)
  get_class()

    get the class object this method belongs to

  get_custom_name()
  get_helper_class()

    Get the C++ helper class, which is used for overriding virtual methods

  get_py_method_def(method_name)

    Get the PyMethodDef entry suitable for this method

  get_py_method_def_flags()

    Get the PyMethodDef flags suitable for this method

  get_wrapper_signature(wrapper_name, extra_wrapper_params=())
  property helper_class

    Get the C++ helper class, which is used for overriding virtual methods

  matches_signature(other)
  set_class(class_)

    set the class object this method belongs to

  set_custom_name(custom_name)
  set_helper_class(helper_class)

    Set the C++ helper class, which is used for overriding virtual methods

class pybindgen.cppmethod.CppNoConstructor(reason)

  Bases: `pybindgen.typehandlers.base.ForwardWrapperBase`

  Class that generates a constructor that raises an exception saying that the class has no constructor.

  Parameters

    reason – string indicating reason why the class cannot be constructed.

  generate(code_sink, class_)

    Generates the wrapper code

    Parameters

      - code_sink – a CodeSink instance that will receive the generated code

      - class – the c++ class wrapper the method belongs to

    Returns the wrapper function name.

  generate_call()

    dummy method, not really called

class pybindgen.cppmethod.CppOverloadedConstructor(wrapper_name)

  Bases: `pybindgen.overloading.OverloadedWrapper`

  Support class for overloaded constructors

  wrapper_name – C/C++ name of the wrapper

  ERROR_RETURN = 'return -1;'
  RETURN_TYPE = 'int'

class pybindgen.cppmethod.CppOverloadedMethod(wrapper_name)

  Bases: `pybindgen.overloading.OverloadedWrapper`

  Support class for overloaded methods

  wrapper_name – C/C++ name of the wrapper

  ERROR_RETURN = 'return NULL;'
  RETURN_TYPE = 'PyObject *'

class pybindgen.cppmethod.CppVirtualMethodParentCaller(method, unblock_threads=None)

  Bases: `pybindgen.cppmethod.CppMethod`

  Class that generates a wrapper that calls a virtual method default implementation in a parent base class.

  Create an object the generates code to wrap a C++ class method.

  Parameters

    - return_value (L{ReturnValue}) – the method return value

    - method_name – name of the method

    - parameters (list of `pybindgen.typehandlers.base.Parameter`) – the method parameters

    - is_static – whether it is a static method

    - template_parameters (list of strings, each element a template parameter expression) – optional list of template parameters needed to invoke the method

    - is_virtual – whether the method is virtual (pure or not)

    - is_const – whether the method has a const modifier on it

    - unblock_threads – whether to release the Python GIL around the method call or not. If None or omitted, use global settings. Releasing the GIL has a small performance penalty, but is recommended if the method is expected to take considerable time to complete, because otherwise no other Python thread is allowed to run until the method completes.

    - is_pure_virtual – whether the method is defined as “pure virtual”, i.e. virtual method with no default implementation in the class being wrapped.

    - custom_name – alternate name to give to the method, in python side.

    - custom_template_method_name – (deprecated) same as parameter ‘custom_name’.

    - visibility (a string (allowed values are 'public', 'protected', 'private')) – visibility of the method within the C++ class

    - deprecated – deprecation state for this API: - False: Not deprecated - True: Deprecated - “message”: Deprecated, and deprecation warning contains the given message

    - throw (list of L{CppException}) – list of C++ exceptions that the function may throw

  property class_

    get the class object this method belongs to

  clone()

    Creates a semi-deep copy of this method wrapper. The returned method wrapper clone contains copies of all parameters, so they can be modified at will.

  generate_call(class_=None)

    virtual method implementation; do not call

  generate_class_declaration(code_sink, extra_wrapper_parameters=())
  generate_declaration(code_sink, extra_wrapper_parameters=())
  generate_parent_caller_method(code_sink)
  get_class()

    get the class object this method belongs to

  get_py_method_def(method_name=None)

    Get the PyMethodDef entry suitable for this method

class pybindgen.cppmethod.CppVirtualMethodProxy(method)

  Bases: `pybindgen.typehandlers.base.ReverseWrapperBase`

  Class that generates a proxy virtual method that calls a similarly named python method.

  Base constructor

  Parameters

    - return_value – type handler for the return value

    - parameters – a list of type handlers for the parameters

  property class_

    Get the class wrapper object (CppClass)

  generate(code_sink)

    generates the proxy virtual method

  generate_declaration(code_sink)
  generate_python_call()

    code to call the python method

  get_class()

    Get the class wrapper object (CppClass)

  get_helper_class()

    Get the C++ helper class, which is used for overriding virtual methods

  property helper_class

    Get the C++ helper class, which is used for overriding virtual methods

  set_helper_class(helper_class)

    Set the C++ helper class, which is used for overriding virtual methods

class pybindgen.cppmethod.CustomCppConstructorWrapper(wrapper_name, wrapper_body)

  Bases: `pybindgen.cppmethod.CppConstructor`

  Adds a custom constructor wrapper. The custom wrapper must be prepared to support overloading, i.e. it must have an additional "PyObject **return_exception" parameter, and raised exceptions must be returned by this parameter.

  Parameters

    - parameters – the constructor parameters

    - deprecated – deprecation state for this API: False=Not deprecated; True=Deprecated; “message”=Deprecated, and deprecation warning contains the given message

    - throw (list of `pybindgen.cppexception.CppException`) – list of C++ exceptions that the constructor may throw

  NEEDS_OVERLOADING_INTERFACE = True
  generate(code_sink, dummy_wrapper_name=None, extra_wrapper_params=())

    Generates the wrapper code :param code_sink: a CodeSink instance that will receive the generated code :returns: the wrapper function name.

  generate_call(*args, **kwargs)

    virtual method implementation; do not call

class pybindgen.cppmethod.CustomCppMethodWrapper(method_name, wrapper_name, wrapper_body=None, flags=('METH_VARARGS', 'METH_KEYWORDS'), docstring=None)

  Bases: `pybindgen.cppmethod.CppMethod`

  Adds a custom method wrapper. The custom wrapper must be prepared to support overloading, i.e. it must have an additional “PyObject **return_exception” parameter, and raised exceptions must be returned by this parameter.

  Create an object the generates code to wrap a C++ class method.

  Parameters

    - return_value (L{ReturnValue}) – the method return value

    - method_name – name of the method

    - parameters (list of `pybindgen.typehandlers.base.Parameter`) – the method parameters

    - is_static – whether it is a static method

    - template_parameters (list of strings, each element a template parameter expression) – optional list of template parameters needed to invoke the method

    - is_virtual – whether the method is virtual (pure or not)

    - is_const – whether the method has a const modifier on it

    - unblock_threads – whether to release the Python GIL around the method call or not. If None or omitted, use global settings. Releasing the GIL has a small performance penalty, but is recommended if the method is expected to take considerable time to complete, because otherwise no other Python thread is allowed to run until the method completes.

    - is_pure_virtual – whether the method is defined as “pure virtual”, i.e. virtual method with no default implementation in the class being wrapped.

    - custom_name – alternate name to give to the method, in python side.

    - custom_template_method_name – (deprecated) same as parameter ‘custom_name’.

    - visibility (a string (allowed values are 'public', 'protected', 'private')) – visibility of the method within the C++ class

    - deprecated – deprecation state for this API: - False: Not deprecated - True: Deprecated - “message”: Deprecated, and deprecation warning contains the given message

    - throw (list of L{CppException}) – list of C++ exceptions that the function may throw

  NEEDS_OVERLOADING_INTERFACE = True
  generate(code_sink, dummy_wrapper_name=None, extra_wrapper_params=())

    Generates the wrapper code code_sink – a CodeSink instance that will receive the generated code method_name – actual name the method will get extra_wrapper_params – extra parameters the wrapper function should receive

    Returns the corresponding PyMethodDef entry string.

  generate_call(*args, **kwargs)

    virtual method implementation; do not call

  generate_declaration(code_sink, extra_wrapper_parameters=())

class pybindgen.cppmethod.DummyParameter(arg)

  Bases: `types.Parameter`

  Accepts either a Parameter object or a tuple as sole parameter. In case it’s a tuple, it is assumed to be a retval spec (*args, **kwargs).

  CTYPES = []
  DIRECTIONS = [1, 2, 3]

    A ‘dummy’ parameter object used for modelling methods that have incomplete or incorrect parameters or return values.

  convert_c_to_python(wrapper)

    Write some code before calling the Python method.

  convert_python_to_c(wrapper)

    Write some code before calling the C method.

class pybindgen.cppmethod.DummyReturnValue(arg)

  Bases: `types.ReturnValue`

  Accepts either a ReturnValue object or a tuple as sole parameter. In case it’s a tuple, it is assumed to be a retval spec (*args, **kwargs).

  CTYPES = []

    A ‘dummy’ return value object used for modelling methods that have incomplete or incorrect parameters or return values.

  convert_c_to_python(wrapper)

    Writes code to convert the C return value the Python return.

  convert_python_to_c(wrapper)

    Writes code to convert the Python return value into the C “retval” variable.

  get_c_error_return()

    Return a “return <value>” code string, for use in case of error