#include "pxr/pxr.h"
#include "pxr/base/tf/api.h"
#include "pxr/base/tf/diagnosticLite.h"
#include "pxr/base/tf/pyError.h"
#include "pxr/base/tf/pyInterpreter.h"
#include "pxr/base/tf/pyLock.h"
#include "pxr/base/tf/pyObjWrapper.h"
#include "pxr/external/boost/python/dict.hpp"
#include "pxr/external/boost/python/extract.hpp"
#include "pxr/external/boost/python/list.hpp"
#include "pxr/external/boost/python/object.hpp"
#include <cstddef>
#include <memory>
#include <string>
#include <type_traits>

Include dependency graph for pyInvoke.h:

Classes
struct	TfPyKwArg

Functions
template<typename T >
PXR_NAMESPACE_OPEN_SCOPE pxr_boost::python::object	Tf_ArgToPy (const T &value)

TF_API pxr_boost::python::object	Tf_ArgToPy (const std::nullptr_t &value)

TF_API void	Tf_BuildPyInvokeKwArgs (pxr_boost::python::dict *kwArgsOut)

template<typename Arg , typename... RestArgs>
void	Tf_BuildPyInvokeKwArgs (pxr_boost::python::dict *kwArgsOut, const Arg &kwArg, RestArgs...rest)

template<typename... RestArgs>
void	Tf_BuildPyInvokeKwArgs (pxr_boost::python::dict *kwArgsOut, const TfPyKwArg &kwArg, RestArgs...rest)

TF_API void	Tf_BuildPyInvokeArgs (pxr_boost::python::list posArgsOut, pxr_boost::python::dict kwArgsOut)

template<typename Arg , typename... RestArgs>
void	Tf_BuildPyInvokeArgs (pxr_boost::python::list posArgsOut, pxr_boost::python::dict kwArgsOut, const Arg &arg, RestArgs...rest)

template<typename... RestArgs>
void	Tf_BuildPyInvokeArgs (pxr_boost::python::list posArgsOut, pxr_boost::python::dict kwArgsOut, const TfPyKwArg &kwArg, RestArgs...rest)

TF_API bool	Tf_PyInvokeImpl (const std::string &moduleName, const std::string &callableExpr, const pxr_boost::python::list &posArgs, const pxr_boost::python::dict &kwArgs, pxr_boost::python::object *resultObjOut)

template<typename... Args>
bool	TfPyInvokeAndReturn (const std::string &moduleName, const std::string &callableExpr, pxr_boost::python::object *resultOut, Args...args)

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

template<typename... Args>
bool	TfPyInvoke (const std::string &moduleName, const std::string &callableExpr, Args...args)

Detailed Description

Flexible, high-level interface for calling Python functions.

Definition in file pyInvoke.h.

Function Documentation

template<typename T >

PXR_NAMESPACE_OPEN_SCOPE pxr_boost::python::object Tf_ArgToPy ( const T & value )

Definition at line 41 of file pyInvoke.h.

TF_API pxr_boost::python::object Tf_ArgToPy ( const std::nullptr_t & value )

TF_API void Tf_BuildPyInvokeArgs	(	pxr_boost::python::list *	posArgsOut,
		pxr_boost::python::dict *	kwArgsOut
	)

template<typename Arg , typename... RestArgs>

void Tf_BuildPyInvokeArgs	(	pxr_boost::python::list *	posArgsOut,
		pxr_boost::python::dict *	kwArgsOut,
		const Arg &	arg,
		RestArgs...	rest
	)

Definition at line 131 of file pyInvoke.h.

template<typename... RestArgs>

void Tf_BuildPyInvokeArgs	(	pxr_boost::python::list *	posArgsOut,
		pxr_boost::python::dict *	kwArgsOut,
		const TfPyKwArg &	kwArg,
		RestArgs...	rest
	)

Definition at line 147 of file pyInvoke.h.

TF_API void Tf_BuildPyInvokeKwArgs ( pxr_boost::python::dict * kwArgsOut )

template<typename Arg , typename... RestArgs>

void Tf_BuildPyInvokeKwArgs	(	pxr_boost::python::dict *	kwArgsOut,
		const Arg &	kwArg,
		RestArgs...	rest
	)

Definition at line 98 of file pyInvoke.h.

template<typename... RestArgs>

void Tf_BuildPyInvokeKwArgs	(	pxr_boost::python::dict *	kwArgsOut,
		const TfPyKwArg &	kwArg,
		RestArgs...	rest
	)

Definition at line 112 of file pyInvoke.h.

TF_API bool Tf_PyInvokeImpl	(	const std::string &	moduleName,
		const std::string &	callableExpr,
		const pxr_boost::python::list &	posArgs,
		const pxr_boost::python::dict &	kwArgs,
		pxr_boost::python::object *	resultObjOut
	)

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.

Definition at line 312 of file pyInvoke.h.

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.

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 234 of file pyInvoke.h.

template<typename... Args>

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

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

Definition at line 271 of file pyInvoke.h.

Classes

Functions

Detailed Description

Function Documentation