PYB11 decorators

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

@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.