HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
pyInvoke.h File Reference
#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 <hboost/python/dict.hpp>
#include <hboost/python/extract.hpp>
#include <hboost/python/list.hpp>
#include <hboost/python/object.hpp>
#include <cstddef>
#include <memory>
#include <string>
#include <type_traits>
+ Include dependency graph for pyInvoke.h:

Go to the source code of this file.

Classes

struct  TfPyKwArg
 

Functions

template<typename T >
PXR_NAMESPACE_OPEN_SCOPE
hboost::python::object 
Tf_ArgToPy (const T &value)
 
TF_API hboost::python::object Tf_ArgToPy (const std::nullptr_t &value)
 
TF_API void Tf_BuildPyInvokeKwArgs (hboost::python::dict *kwArgsOut)
 
template<typename Arg , typename... RestArgs>
void Tf_BuildPyInvokeKwArgs (hboost::python::dict *kwArgsOut, const Arg &kwArg, RestArgs...rest)
 
template<typename... RestArgs>
void Tf_BuildPyInvokeKwArgs (hboost::python::dict *kwArgsOut, const TfPyKwArg &kwArg, RestArgs...rest)
 
TF_API void Tf_BuildPyInvokeArgs (hboost::python::list *posArgsOut, hboost::python::dict *kwArgsOut)
 
template<typename Arg , typename... RestArgs>
void Tf_BuildPyInvokeArgs (hboost::python::list *posArgsOut, hboost::python::dict *kwArgsOut, const Arg &arg, RestArgs...rest)
 
template<typename... RestArgs>
void Tf_BuildPyInvokeArgs (hboost::python::list *posArgsOut, hboost::python::dict *kwArgsOut, const TfPyKwArg &kwArg, RestArgs...rest)
 
TF_API bool Tf_PyInvokeImpl (const std::string &moduleName, const std::string &callableExpr, const hboost::python::list &posArgs, const hboost::python::dict &kwArgs, hboost::python::object *resultObjOut)
 
template<typename... Args>
bool TfPyInvokeAndReturn (const std::string &moduleName, const std::string &callableExpr, hboost::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 hboost::python::object Tf_ArgToPy ( const T &  value)

Definition at line 58 of file pyInvoke.h.

TF_API hboost::python::object Tf_ArgToPy ( const std::nullptr_t &  value)
TF_API void Tf_BuildPyInvokeArgs ( hboost::python::list *  posArgsOut,
hboost::python::dict *  kwArgsOut 
)
template<typename Arg , typename... RestArgs>
void Tf_BuildPyInvokeArgs ( hboost::python::list *  posArgsOut,
hboost::python::dict *  kwArgsOut,
const Arg &  arg,
RestArgs...  rest 
)

Definition at line 148 of file pyInvoke.h.

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

Definition at line 164 of file pyInvoke.h.

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

Definition at line 115 of file pyInvoke.h.

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

Definition at line 129 of file pyInvoke.h.

TF_API bool Tf_PyInvokeImpl ( const std::string moduleName,
const std::string callableExpr,
const hboost::python::list &  posArgs,
const hboost::python::dict &  kwArgs,
hboost::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 329 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.
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.

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

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

Definition at line 288 of file pyInvoke.h.