PYB11 decorators

@PYB11ignore

Specifies that the decorated object should be ignored by PYB11Generator, i.e., not processed to produce any pybind11 binding output.

@PYB11ignoreTest

Similar to PYB11ignore, except this form allows the user to pass a function (typically a Python lambda) that can actively test at generation time if the method should be ignored.

The function passed to @PYB11ignoreTest is typically of the form:

lambda meth_attrs, klass_attrs: <function body>

where meth_attrs are PYB11 attributes associated with the method and klass_attrs are those associated with the enclosing class.

See the discussion in Ignoring methods at generation time for particular instances for an example and further discussion.

@PYB11template("type1", "type2", ...)

Indicates the object should be treated as a C++ template. Accepts any number of strings which represent the names of the template arguments.

The succeeding python class or function can use the specified template argument strings as patterns for substitation with python dictionary string replacement. So if we are binding a C++ templated function:

template<typename T>
T manipulate(const T& val);

The corresponding PYB11 template specfication would look like:

@PYB11template("T")
def manipulate(val = "const %(T)s"):
    return "%(T)s"

@PYB11template_dict

Explicitly specifies the dictionary of template args to values for use with @PYB11template types.

NOTE: this is a highly unusual pattern to need/use. It is preferable to use the ordinary PYB11 template instantion methods PYB11TemplateClass, PYB11TemplateMethod, or PYB11TemplateFunction.

@PYB11singleton

Specifies that the decorated object should be treated as a C++ singleton.

@PYB11holder(holder_type)

Specify a special C++ holder for the generated type in pybind, rather than the usual default std::unique_ptr. See pybind11 documentation on using shared_ptr as a holder type.

@PYB11dynamic_attr

Make the wrapped class modifiable, i.e., allow attributes to be added dynamically to an instance of the class in python. See pybind11 documentation about dynamic attributes.

@PYB11namespace("val")

Set the namespace the C++ type should be found in.

@PYB11cppname("val")

Give a value for the C++ name of the decorated function, class, or method. Overrides the default assumption that the C++ name is the same as that given for the object in the PYB11 python binding file.

@PYB11pycppname("val")

Simultaneously set the Python and C++ name of the decorated function, class, or method. Shorthand for specifying both @PYB11pyname and @PYB11cppname to the given "val".

@PYB11virtual

Mark a class method as virtual.

@PYB11pure_virtual

Mark a class method as pure virtual, making the class abstract.

@PYB11protected

Mark a class method as protected.

@PYB11const

Mark a class method as const.

@PYB11static

Mark a class method as static.

@PYB11operator

Mark a class method as an operator. See `pybind11 discussion of py::is_operator in the discussion of operator overloading<https://pybind11.readthedocs.io/en/stable/advanced/classes.html?highlight=is_operator#operator-overloading>`_.

@PYB11noconvert

Applies py::noconvert to all the arguments of a method to prevent automatic conversion. See pybind11 discussion of py::.

@PYB11implementation("val")

Give an implementation for the bound function or method. This is typically used to specify lambda function implementations, or explicitly call a helper method.

@PYB11returnpolicy("val")

Specify a pybind11 return policy for the return value of a function or method. This is a tricky topic that if misused can create memory errors, but is at times absolutely necessary to get the expected behavior from the underlying C++ code and types. Before using this method carefully read the pybind11 discussion about Return value policies.

@PYB11keepalive(a, b)

Tie the lifetime of objects in the return value/argument spec together, where the arguments (a, b) are integers indicating the order of the arguments to tie together (0 refers to the return value). This is another way of specifying memory policies, similar to returnpolicy. Carefully read the pybind11 discussion of the keep_alive directive in Additional call policies.

@PYB11call_guard("val")

Specify a pybind11 call_guard for a function or method. See the discussion of pybind11:call_policies for examples of call_guards.

@PYB11module("val")

Indicate the object should be imported from the specified python module. This is useful for classes wrapped in one module which are needed in another, such as for inheritance.