pyInvoke.h File Reference

Flexible, high-level interface for calling Python functions. More...

Include dependency graph for pyInvoke.h:

Go to the source code of this file.

Classes
struct	TfPyKwArg
	Wrapper object for a keyword-argument pair in a call to TfPyInvoke*. More...

Functions
template<typename Result , typename... Args>
bool	TfPyInvokeAndExtract (const std::string &moduleName, const std::string &callableExpr, Result *resultOut, Args...args)
	Call a Python function and obtain its return value. More...
template<typename... Args>
bool	TfPyInvokeAndReturn (const std::string &moduleName, const std::string &callableExpr, boost::python::object *resultOut, Args...args)
	A version of TfPyInvokeAndExtract that provides the Python function's return value as a boost::python::object, rather than extracting a particular C++ type from it. More...
template<typename... Args>
bool	TfPyInvoke (const std::string &moduleName, const std::string &callableExpr, Args...args)
	A version of TfPyInvokeAndExtract that ignores the Python function's return value. More...

Detailed Description

Flexible, high-level interface for calling Python functions.

Definition in file pyInvoke.h.

Function Documentation

bool TfPyInvoke	(	const std::string &	moduleName,
		const std::string &	callableExpr,
		Args...	args
	)

A version of TfPyInvokeAndExtract that ignores the Python function's return value.

Definition at line 329 of file pyInvoke.h.

bool TfPyInvokeAndExtract	(	const std::string &	moduleName,
		const std::string &	callableExpr,
		Result *	resultOut,
		Args...	args
	)

Call a Python function and obtain its return value.

Example:

*  // Call MyModule.MyFunction(arg1, arg2), which returns a string.
*  std::string result;
*  const bool ok = TfPyInvokeAndExtract(
*      "MyModule", "MyFunction", &result, arg1Value, arg2Value);
*  

moduleName is the name of the module in which to find the function. This name will be directly imported in an import statement, so anything that you know is in sys.path should work. The module name will also be prepended to callableExpr to look up the function.

callableExpr is a Python expression that, when appended to moduleName (with an intervening dot), yields a callable object. Typically this is just a function name, optionally prefixed with object names (such as a class in which the callable resides).

resultOut is a pointer that will receive the Python function's return value. A from-Python converter must be registered for the type of *resultOut.

args is zero or more function arguments, of any types for which to-Python conversions are registered. Any nullptr arguments are converted to None. args may also contain TfPyKwArg objects to pass keyword arguments. As in Python, once a keyword argument is passed, all remaining arguments must also be keyword arguments.

The return value of TfPyInvokeAndExtract is true if the call completed, false otherwise. When the return value is false, at least one TfError should have been raised, describing the failure. TfPyInvokeAndExtract never raises exceptions.

It should be safe to call this function without doing any other setup first. It is not necessary to call TfPyInitialize or lock the GIL; this function does those things itself.

If you don't need the function's return value, call TfPyInvoke instead.

If you need the function's return value, but the return value isn't guaranteed to be a consistent type that's convertible to C++, call TfPyInvokeAndReturn instead. This includes cases where the function's return value may be None.

Definition at line 251 of file pyInvoke.h.

bool TfPyInvokeAndReturn	(	const std::string &	moduleName,
		const std::string &	callableExpr,
		boost::python::object *	resultOut,
		Args...	args
	)

A version of TfPyInvokeAndExtract that provides the Python function's return value as a boost::python::object, rather than extracting a particular C++ type from it.

Definition at line 288 of file pyInvoke.h.