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

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

Static Public Member Functions
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:

template <typename T>

T doSomething(std::string const & argument);

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},
            dtype,
            TemplateInvoker::Tag<int, float, double>()
        );
    },
    "argument"_a
);

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); },
            dtype,
            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

using lsst::utils::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/2]

lsst::utils::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.

◆ TemplateInvoker() [2/2]

lsst::utils::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()

template<typename Function , typename ... TypesToTry>

pybind11::object lsst::utils::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]	function	Callable 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]	dtype	NumPy dtype object indicating the template specialization to invoke.
[in]	typesToTry	A `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.

◆ handleErrorDefault()

static pybind11::object lsst::utils::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.

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

include/lsst/utils/python/TemplateInvoker.h

Classes

Public Types

Public Member Functions

Static Public Member Functions