LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
lsst::cpputils::python::TemplateInvoker Class Reference

A helper class for wrapping C++ template functions as Python functions with dtype arguments. More...

#include <TemplateInvoker.h>

Classes

struct  Tag
 A simple tag type used to pass one or more types as a function argument. More...
 

Public Types

using OnErrorCallback = std::function< pybind11::object(pybind11::dtype const &dtype)>
 Callback type for handling unmatched-type errors. More...
 
using OnErrorCallback = std::function< pybind11::object(pybind11::dtype const &dtype)>
 Callback type for handling unmatched-type errors. More...
 

Public Member Functions

 TemplateInvoker (OnErrorCallback onError)
 Construct a TemplateInvoker that calls the given object when no match is found. More...
 
 TemplateInvoker ()
 Construct a TemplateInvoker that calls handleErrorDefault when no match is found. More...
 
template<typename Function , typename ... TypesToTry>
pybind11::object apply (Function function, pybind11::dtype const &dtype, Tag< TypesToTry... > typesToTry) const
 Call and return function(static_cast<T>(0)) with the type T that matches a given NumPy dtype object. More...
 
 TemplateInvoker (OnErrorCallback onError)
 Construct a TemplateInvoker that calls the given object when no match is found. More...
 
 TemplateInvoker ()
 Construct a TemplateInvoker that calls handleErrorDefault when no match is found. More...
 
template<typename Function , typename ... TypesToTry>
pybind11::object apply (Function function, pybind11::dtype const &dtype, Tag< TypesToTry... > typesToTry) const
 Call and return function(static_cast<T>(0)) with the type T that matches a given NumPy dtype object. More...
 

Static Public Member Functions

static pybind11::object handleErrorDefault (pybind11::dtype const &dtype)
 Callback used for handling unmatched-type errors by default. More...
 
static pybind11::object handleErrorDefault (pybind11::dtype const &dtype)
 Callback used for handling unmatched-type errors by default. More...
 

Detailed Description

A helper class for wrapping C++ template functions as Python functions with dtype arguments.

TemplateInvoker takes a templated callable object, a pybind11::dtype object, and a sequence of supported C++ types via its nested Tag struct. The callable is invoked with a scalar argument of the type matching the dtype object. If none of the supported C++ types match, a different error callback is invoked instead.

As an example, we'll wrap this function:

TemplateInvoker provides a default error callback, which we'll use here (otherwise you'd need to pass one when constructing the TemplateInvoker).

For the main callback, we'll define this helper struct:

struct DoSomethingHelper {
template <typename T>
T operator()(T) const {
return doSomething<T>(argument);
}
std::string argument;
};

The pybind11 wrapper for doSomething is then another lambda that uses TemplateInvoker::apply to call the helper:

mod.def(
"doSomething",
[](std::string const & argument, py::dtype const & dtype) {
return TemplateInvoker().apply(
DoSomethingHelper{argument},
TemplateInvoker::Tag<int, float, double>()
);
},
"argument"_a
);
TemplateInvoker()
Construct a TemplateInvoker that calls handleErrorDefault when no match is found.

The type returned by the helper callable's operator() can be anything pybind11 knows how to convert to Python.

While defining a full struct with a templated operator() makes it more obvious what TemplateInvoker is doing, it's much more concise to use a universal lambda with the decltype operator. This wrapper is equivalent to the one above, but it doesn't need DoSomethingHelper:

mod.def(
"doSomething",
[](std::string const & argument, py::dtype const & dtype) {
return TemplateInvoker().apply(
[&argument](auto t) { return doSomething<decltype(t)>(argument); },
TemplateInvoker::Tag<int, float, double>()
);
},
"argument"_a
);

Note that the value of t here doesn't matter; what's important is that its C++ type corresponds to the type passed in the dtype argument. So instead of using that value, we use the decltype operator to extract that type and use it as a template parameter.

Definition at line 106 of file TemplateInvoker.h.

Member Typedef Documentation

◆ OnErrorCallback [1/2]

using lsst::cpputils::python::TemplateInvoker::OnErrorCallback = std::function<pybind11::object(pybind11::dtype const & dtype)>

Callback type for handling unmatched-type errors.

Definition at line 114 of file TemplateInvoker.h.

◆ OnErrorCallback [2/2]

using lsst::cpputils::python::TemplateInvoker::OnErrorCallback = std::function<pybind11::object(pybind11::dtype const & dtype)>

Callback type for handling unmatched-type errors.

Definition at line 114 of file TemplateInvoker.h.

Constructor & Destructor Documentation

◆ TemplateInvoker() [1/4]

lsst::cpputils::python::TemplateInvoker::TemplateInvoker ( OnErrorCallback  onError)
inlineexplicit

Construct a TemplateInvoker that calls the given object when no match is found.

The callback should have the same signature as handleErrorDefault; the dtype actually passed from Python is passed so it can be included in error messages.

Definition at line 129 of file TemplateInvoker.h.

129 : _onError(std::move(onError)) {}
T move(T... args)

◆ TemplateInvoker() [2/4]

lsst::cpputils::python::TemplateInvoker::TemplateInvoker ( )
inline

Construct a TemplateInvoker that calls handleErrorDefault when no match is found.

Definition at line 132 of file TemplateInvoker.h.

static pybind11::object handleErrorDefault(pybind11::dtype const &dtype)
Callback used for handling unmatched-type errors by default.

◆ TemplateInvoker() [3/4]

lsst::cpputils::python::TemplateInvoker::TemplateInvoker ( OnErrorCallback  onError)
inlineexplicit

Construct a TemplateInvoker that calls the given object when no match is found.

The callback should have the same signature as handleErrorDefault; the dtype actually passed from Python is passed so it can be included in error messages.

Definition at line 129 of file TemplateInvoker.h.

129 : _onError(std::move(onError)) {}

◆ TemplateInvoker() [4/4]

lsst::cpputils::python::TemplateInvoker::TemplateInvoker ( )
inline

Construct a TemplateInvoker that calls handleErrorDefault when no match is found.

Definition at line 132 of file TemplateInvoker.h.

Member Function Documentation

◆ apply() [1/2]

template<typename Function , typename ... TypesToTry>
pybind11::object lsst::cpputils::python::TemplateInvoker::apply ( Function  function,
pybind11::dtype const &  dtype,
Tag< TypesToTry... >  typesToTry 
) const
inline

Call and return function(static_cast<T>(0)) with the type T that matches a given NumPy dtype object.

Parameters
[in]functionCallable object to invoke. Must have an overloaded operator() that takes any T in the sequence TypesToTry, and a fail(py::dtype) method to handle the case where none of the given types match.
[in]dtypeNumPy dtype object indicating the template specialization to invoke.
[in]typesToTryA Tag instance parameterized with the list of types to try to match to dtype.
Returns
the result of calling function with the matching type, after converting it into a Python object.
Exception Safety
the same as the exception safety of function

Definition at line 156 of file TemplateInvoker.h.

160  {
161  return _apply(function, dtype, typesToTry);
162  }

◆ apply() [2/2]

template<typename Function , typename ... TypesToTry>
pybind11::object lsst::cpputils::python::TemplateInvoker::apply ( Function  function,
pybind11::dtype const &  dtype,
Tag< TypesToTry... >  typesToTry 
) const
inline

Call and return function(static_cast<T>(0)) with the type T that matches a given NumPy dtype object.

Parameters
[in]functionCallable object to invoke. Must have an overloaded operator() that takes any T in the sequence TypesToTry, and a fail(py::dtype) method to handle the case where none of the given types match.
[in]dtypeNumPy dtype object indicating the template specialization to invoke.
[in]typesToTryA Tag instance parameterized with the list of types to try to match to dtype.
Returns
the result of calling function with the matching type, after converting it into a Python object.
Exception Safety
the same as the exception safety of function

Definition at line 156 of file TemplateInvoker.h.

160  {
161  return _apply(function, dtype, typesToTry);
162  }

◆ handleErrorDefault() [1/2]

static pybind11::object lsst::cpputils::python::TemplateInvoker::handleErrorDefault ( pybind11::dtype const &  dtype)
inlinestatic

Callback used for handling unmatched-type errors by default.

Definition at line 117 of file TemplateInvoker.h.

117  {
118  PyErr_Format(PyExc_TypeError, "dtype '%R' not supported.", dtype.ptr());
119  throw pybind11::error_already_set();
120  }

◆ handleErrorDefault() [2/2]

static pybind11::object lsst::cpputils::python::TemplateInvoker::handleErrorDefault ( pybind11::dtype const &  dtype)
inlinestatic

Callback used for handling unmatched-type errors by default.

Definition at line 117 of file TemplateInvoker.h.

117  {
118  PyErr_Format(PyExc_TypeError, "dtype '%R' not supported.", dtype.ptr());
119  throw pybind11::error_already_set();
120  }

The documentation for this class was generated from the following file: