PYB11 special functions and classes
This section describes the special functions and classes defined in PYB11Generator for use in createing python bindings. Note we use the convention that PYB11 internals always start with the PYB11
prefix.
- PYB11generateModule(pymodule[, modname=None, filename=None])
Inspect the function and class definitions in
pymodule
, and write a C++ file containing pybind11 statements to bind those interfaces.pymodule
: the module to be introspected for the interfacemodname
: optionally specify a different name for the generated Python module to be imported under. Defaults topymodule
.filename
: a file name for the generated C++ file. If specified, the output is written to the given name, otherwise output will be written topymodule.cc
- PYB11TemplateFunction(func_template, template_parameters[, cppname = None, pyname = None, docext = ""])
Instantiate a function template (
func_template
) that was decorated by@PYB11template
.func_template
: The template function definitiontemplate_parameters
: A single string (for a single template parameter function) or tuple of strings (for multiple template parameters), one for each template parameter defined by@PYB11template
onfunc_template
.cppname
: The name of the C++ function template, if different from that used forfunc_template
.pyname
: The name of the resulting Python function; defaults to the name of the instance created for this invocation ofPYB11TemplateFunction
.docext
: An optional string extension to be applied to the docstring associated withfunc_template
.
- PYB11attr([value=None, pyname=None])
Create an attribute in a module; corresponds to the pybind11 command
attr
.value
: define the C++ name this variable corresponds to. IfNone
, defaults to the name of the local python variable.pyname
: define the generated python attribte name. IfNone
, defaults to the name of the local python variable.
- PYB11readwrite([static=False, pyname=None, cppname=None, returnpolicy=None, doc=None])
Define a readwrite class attribute; corresponds to pybind11
def_readwrite
.static
: IfTrue
, specifies the bound attribute is static.pyname
: Optionally specify the Python name of the attribute. IfNone
, assumes the Python name is the name of Python variable instance.cppname
: Optionally specify the C++ name of the attribute. IfNone
, assumes the C++ name is the name of Python variable instance.
returnpolicy
: Specify a special return policy for how to handle the memory of the return value. Read pybind11 documentation at Return value policies.
doc
: Optionally give a docstring.
- PYB11readonly([static=False, pyname=None, cppname=None, returnpolicy=None, doc=None])
Define a readonly class attribute; corresponds to pybind11
def_readonly
.static
: IfTrue
, specifies the bound attribute is static.pyname
: Optionally specify the Python name of the attribute. IfNone
, assumes the Python name is the name of Python variable instance.cppname
: Optionally specify the C++ name of the attribute. IfNone
, assumes the C++ name is the name of Python variable instance.returnpolicy
: Specify a special return policy for how to handle the memory of the return value. Read pybind11 documentation at Return value policies.doc
: Optionally give a docstring.
- PYB11property([returnType = None, getter = None, setter = None, doc = None, getterraw = None, setterraw = None, getterconst = True, setterconst = False, static = None, returnpolicy = None])
Helper to setup a class property.
returnType
: Specify the C++ type of the propertygetter
: A string with the name of the getter method. IfNone
, assumes the getter C++ specification looks likereturnType (klass::*)() const
.setter
: A string with the name of the setter method. IfNone
, assumes the setter C++ specification looks likevoid (klass::*)(returnType& val)
.doc
: Specify a document string for the property.getterraw
: Optionally specify raw coding for the getter method. Generally this is used to insert a C++ lambda function. Only one ofgetter
orgetterraw
may be specified.setterraw
: Optionally specify raw coding for the setter method. Generally this is used to insert a C++ lambda function. Only one ofsetter
orsetterraw
may be specified.getterconst
: Specify ifgetter
is a const method.setterconst
: Specify ifsetter
is a const method.static
: IfTrue
, make this a static property.returnpolicy
: Specify a special return policy for how to handle the memory of the return value. Read pybind11 documentation at Return value policies.
- PYB11TemplateMethod(func_template, template_parameters[, cppname = None, pyname = None, docext = ""])
Instantiate a class method (
func_template
) that was decorated by@PYB11template
.func_template
: The template method definitiontemplate_parameters
: A single string (for a single template parameter method) or tuple of strings (for multiple template parameters), one for each template parameter defined by@PYB11template
onfunc_template
.cppname
: The name of the C++ method template, if different from that used forfunc_template
.pyname
: The name of the resulting Python method; defaults to the name of the instance created for this invocation ofPYB11TemplateMethod
.docext
: An optional string extension to be applied to the docstring associated withfunc_template
.
- PYB11TemplateClass(klass_template, template_parameters[, cppname = None, pyname = None, docext = ""])
Instantiate a class template (
klass_template
) that was decorated by@PYB11template
.klass_template
: The template class definitiontemplate_parameters
: A single string (for a single template parameter class) or tuple of strings (for multiple template parameters), one for each template parameter defined by@PYB11template
onklass_template
.cppname
: The name of the C++ class template, if different from that used forklass_template
.pyname
: The name of the resulting Python class; defaults to the name of the instance created for this invocation ofPYB11TemplateClass
.docext
: An optional string extension to be applied to the docstring associated withklass_template
.
- PYB11enum(values[, name=None, namespace="", cppname=None, export_values=False, doc=None])
Declare a C++ enum for wrapping in pybind11 – see pybind11 docs.
values
: a tuple of strings listing the possible values for the enumname: set the name of enum type in Python.
None
defaults to the name of the instance given this enum declaration instance.namespace: an optional C++ namespace the enum lives in.
cppname: the C++ name of the enum.
None
defaults to the same asname
.export_values: if
True
, causes the enum values to be exported into the enclosing scope (like an old-style C enum).doc: an optional document string.
- PYB11_bind_vector(element[, opaque=False, local=None])
Bind an STL::vector explicitly. This is essentially a thin wrapper around the pybind11
py::bind_vector
function (see Binding STL containers).element
: the C++ element type of thestd::vector
opaque
: ifTrue
, causes the bound STL vector to be “opaque”, so elements can be changed in place rather than accessed as copies. See Binding STL containers.local
: determines whether the binding of the STL vector should be module local or not; once again, see Binding STL containers.
- PYB11_bind_map(key, value[, opaque=False, local=None])
Bind an STL::map explicitly. This is a thin wrapper around the pybind11
py::bind_map
function (see Binding STL containers).key
: the C++ key typevalue
: the C++ value typeopaque
: ifTrue
, causes the bound STL map to be “opaque”, so elements can be changed in place rather than accessed as copies. See Binding STL containers.local
: determines whether the binding of the STL map should be module local or not; once again, see Binding STL containers.
- PYB11_inject(fromcls, tocls[, virtual=None, pure_virtual=None])
Convenience method to inject methods from class
fromcls
intotocls
. This is intended as a utility to help avoiding writing redundant methods common to many classes over and over again. Instead a convenience class can be defined containing the shared methods (typically screened from generation by@PYB11ignore
), and thenPYB11_inject
is used to copy those methods into the target classes.fromcls
: Python class with methods we want to copy from.tocls
: Python class we’re copying methods to.virtual
: ifTrue
, force all methods we’re copying to be treated as virtual.pure_virtual
: ifTrue
, force all methods we’re copying to be treated as pure virtual.