This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
pyUtils.h File Reference

Miscellaneous Utilities for dealing with script. More...

+ Include dependency graph for pyUtils.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define TF_PY_REPR_PREFIX
 A macro which expands to the proper repr prefix for a library.
 

Functions

TF_API bool TfPyIsInitialized ()
 Returns true if python is initialized.
 
TF_API void TfPyThrowIndexError (const char *msg)
 Raises a Python IndexError with the given error msg and throws a pxr_boost::python::error_already_set exception.
 
void TfPyThrowIndexError (std::string const &msg)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
TF_API void TfPyThrowRuntimeError (const char *msg)
 Raises a Python RuntimeError with the given error msg and throws a pxr_boost::python::error_already_set exception.
 
void TfPyThrowRuntimeError (std::string const &msg)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
TF_API void TfPyThrowStopIteration (const char *msg)
 Raises a Python StopIteration with the given error msg and throws a pxr_boost::python::error_already_set exception.
 
void TfPyThrowStopIteration (std::string const &msg)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
TF_API void TfPyThrowKeyError (const char *msg)
 Raises a Python KeyError with the given error msg and throws a pxr_boost::python::error_already_set exception.
 
void TfPyThrowKeyError (std::string const &msg)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
TF_API void TfPyThrowValueError (const char *msg)
 Raises a Python ValueError with the given error msg and throws a pxr_boost::python::error_already_set exception.
 
void TfPyThrowValueError (std::string const &msg)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
TF_API void TfPyThrowTypeError (const char *msg)
 Raises a Python TypeError with the given error msg and throws a pxr_boost::python::error_already_set exception.
 
void TfPyThrowTypeError (std::string const &msg)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
TF_API bool TfPyIsNone (pxr_boost::python::object const &obj)
 Return true iff obj is None.
 
TF_API bool TfPyIsNone (pxr_boost::python::handle<> const &obj)
 Return true iff obj is None.
 
template<typename T >
pxr_boost::python::object TfPyObject (T const &t, bool complainOnFailure=true)
 Return a python object for the given C++ object, loading the appropriate wrapper code if necessary.
 
pxr_boost::python::object TfPyObject (PyObject *t, bool complainOnFailure=true)
 
TF_API std::string TfPyObjectRepr (pxr_boost::python::object const &t)
 Return repr(t).
 
template<typename T >
std::string TfPyRepr (T const &t)
 Return repr(t).
 
template<typename T >
std::string TfPyRepr (const std::vector< T > &v)
 Return repr(t) for a vector as a python list.
 
TF_API pxr_boost::python::object TfPyEvaluate (std::string const &expr, pxr_boost::python::dict const &extraGlobals=pxr_boost::python::dict())
 Evaluate python expression expr with all the known script modules imported under their standard names.
 
TF_API int64_t TfPyNormalizeIndex (int64_t index, uint64_t size, bool throwError=false)
 Return a positive index in the range [0,size).
 
TF_API std::string TfPyGetClassName (pxr_boost::python::object const &obj)
 Return the name of the class of obj.
 
TF_API pxr_boost::python::object TfPyGetClassObject (std::type_info const &type)
 Return the python class object for type if type has been wrapped.
 
template<typename T >
pxr_boost::python::object TfPyGetClassObject ()
 Return the python class object for T if T has been wrapped.
 
template<typename T >
void TfPyWrapOnce (std::function< void()> const &wrapFunc)
 Invokes wrapFunc to wrap type T if T is not already wrapped.
 
template<class Map >
pxr_boost::python::dict TfPyCopyMapToDictionary (Map const &map)
 Creates a python dictionary from a std::map.
 
template<class Seq >
pxr_boost::python::list TfPyCopySequenceToList (Seq const &seq)
 
template<class Seq >
pxr_boost::python::object TfPyCopySequenceToSet (Seq const &seq)
 Create a python set from an iterable sequence.
 
template<class Seq >
pxr_boost::python::tuple TfPyCopySequenceToTuple (Seq const &seq)
 
TF_API pxr_boost::python::object TfPyCopyBufferToByteArray (const char *buffer, size_t size)
 Create a python bytearray from an input buffer and size.
 
TF_API std::vector< std::string > TfPyGetTraceback ()
 Return a vector of strings containing the current python traceback.
 
TF_API bool TfPySetenv (const std::string &name, const std::string &value)
 Set an environment variable in os.environ.
 
TF_API bool TfPyUnsetenv (const std::string &name)
 Remove an environment variable from os.environ.
 
template<typename T >
bool TfPyEvaluateAndExtract (const std::string &expr, T *t)
 Safely evaluates expr and extracts the return object of type T.
 
TF_API void TfPyPrintError ()
 Print a standard traceback to sys.stderr and clear the error indicator.
 

Detailed Description

Miscellaneous Utilities for dealing with script.

Definition in file pyUtils.h.

Macro Definition Documentation

◆ TF_PY_REPR_PREFIX

#define TF_PY_REPR_PREFIX

A macro which expands to the proper repr prefix for a library.

This is the "canonical" name of the module that the system uses to identify it followed by a '.'. This can be used in the implementation of repr

Definition at line 42 of file pyUtils.h.

Function Documentation

◆ TfPyCopyBufferToByteArray()

TF_API pxr_boost::python::object TfPyCopyBufferToByteArray ( const char *  buffer,
size_t  size 
)

Create a python bytearray from an input buffer and size.

If a size of zero is passed in this function will return a valid python bytearray of size zero.

An invalid object handle is returned on failure.

◆ TfPyCopyMapToDictionary()

pxr_boost::python::dict TfPyCopyMapToDictionary ( Map const &  map)

Creates a python dictionary from a std::map.

Definition at line 258 of file pyUtils.h.

◆ TfPyCopySequenceToList()

pxr_boost::python::list TfPyCopySequenceToList ( Seq const &  seq)

Definition at line 267 of file pyUtils.h.

◆ TfPyCopySequenceToSet()

pxr_boost::python::object TfPyCopySequenceToSet ( Seq const &  seq)

Create a python set from an iterable sequence.

If Seq::value_type is not hashable, TypeError is raised via throwing pxr_boost::python::error_already_set.

Definition at line 281 of file pyUtils.h.

◆ TfPyCopySequenceToTuple()

pxr_boost::python::tuple TfPyCopySequenceToTuple ( Seq const &  seq)

Definition at line 297 of file pyUtils.h.

◆ TfPyEvaluate()

TF_API pxr_boost::python::object TfPyEvaluate ( std::string const &  expr,
pxr_boost::python::dict const &  extraGlobals = pxr_boost::python::dict() 
)

Evaluate python expression expr with all the known script modules imported under their standard names.

Additional globals may be provided in the extraGlobals dictionary.

◆ TfPyEvaluateAndExtract()

bool TfPyEvaluateAndExtract ( const std::string &  expr,
T *  t 
)

Safely evaluates expr and extracts the return object of type T.

If successful, returns true and sets *t to the return value, otherwise returns false.

Definition at line 375 of file pyUtils.h.

◆ TfPyGetClassName()

TF_API std::string TfPyGetClassName ( pxr_boost::python::object const &  obj)

Return the name of the class of obj.

◆ TfPyGetClassObject() [1/2]

pxr_boost::python::object TfPyGetClassObject ( )

Return the python class object for T if T has been wrapped.

Otherwise return None.

Definition at line 215 of file pyUtils.h.

◆ TfPyGetClassObject() [2/2]

TF_API pxr_boost::python::object TfPyGetClassObject ( std::type_info const &  type)

Return the python class object for type if type has been wrapped.

Otherwise return None.

◆ TfPyGetTraceback()

TF_API std::vector< std::string > TfPyGetTraceback ( )

Return a vector of strings containing the current python traceback.

The vector contains the same strings that python's traceback.format_stack() returns.

◆ TfPyIsInitialized()

TF_API bool TfPyIsInitialized ( )

Returns true if python is initialized.

◆ TfPyIsNone() [1/2]

TF_API bool TfPyIsNone ( pxr_boost::python::handle<> const &  obj)

Return true iff obj is None.

◆ TfPyIsNone() [2/2]

TF_API bool TfPyIsNone ( pxr_boost::python::object const &  obj)

Return true iff obj is None.

◆ TfPyNormalizeIndex()

TF_API int64_t TfPyNormalizeIndex ( int64_t  index,
uint64_t  size,
bool  throwError = false 
)

Return a positive index in the range [0,size).

If throwError is true, this will throw an index error if the resulting index is out of range.

◆ TfPyObject() [1/2]

pxr_boost::python::object TfPyObject ( PyObject *  t,
bool  complainOnFailure = true 
)
inline

Definition at line 148 of file pyUtils.h.

◆ TfPyObject() [2/2]

pxr_boost::python::object TfPyObject ( T const &  t,
bool  complainOnFailure = true 
)

Return a python object for the given C++ object, loading the appropriate wrapper code if necessary.

Spams users if complainOnFailure is true and conversion fails.

Definition at line 127 of file pyUtils.h.

◆ TfPyObjectRepr()

TF_API std::string TfPyObjectRepr ( pxr_boost::python::object const &  t)

Return repr(t).

Calls PyObject_Repr on the given python object.

◆ TfPyPrintError()

TF_API void TfPyPrintError ( )

Print a standard traceback to sys.stderr and clear the error indicator.

If the error is a KeyboardInterrupt then this does nothing. Call this function only when the error indicator is set.

◆ TfPyRepr() [1/2]

std::string TfPyRepr ( const std::vector< T > &  v)

Return repr(t) for a vector as a python list.

Definition at line 172 of file pyUtils.h.

◆ TfPyRepr() [2/2]

std::string TfPyRepr ( T const &  t)

Return repr(t).

Converts t to its equivalent python object and then calls PyObject_Repr on that.

Definition at line 163 of file pyUtils.h.

◆ TfPySetenv()

TF_API bool TfPySetenv ( const std::string &  name,
const std::string &  value 
)

Set an environment variable in os.environ.

This function is equivalent to

def PySetenv(name, value):
try:
import os
os.environ[name] = value
return True
except:
return False

Calling this function without first initializing Python is an error and returns false.

Note that this function will import the os module, causing os.environ to be poputated. All modifications to the environment after os has been imported must be made with this function or TfSetenv if it important that they appear in os.environ.

◆ TfPyThrowIndexError() [1/2]

TF_API void TfPyThrowIndexError ( const char *  msg)

Raises a Python IndexError with the given error msg and throws a pxr_boost::python::error_already_set exception.

Callers must hold the GIL before calling this function.

◆ TfPyThrowIndexError() [2/2]

void TfPyThrowIndexError ( std::string const &  msg)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 54 of file pyUtils.h.

◆ TfPyThrowKeyError() [1/2]

TF_API void TfPyThrowKeyError ( const char *  msg)

Raises a Python KeyError with the given error msg and throws a pxr_boost::python::error_already_set exception.

Callers must hold the GIL before calling this function.

◆ TfPyThrowKeyError() [2/2]

void TfPyThrowKeyError ( std::string const &  msg)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 87 of file pyUtils.h.

◆ TfPyThrowRuntimeError() [1/2]

TF_API void TfPyThrowRuntimeError ( const char *  msg)

Raises a Python RuntimeError with the given error msg and throws a pxr_boost::python::error_already_set exception.

Callers must hold the GIL before calling this function.

◆ TfPyThrowRuntimeError() [2/2]

void TfPyThrowRuntimeError ( std::string const &  msg)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 65 of file pyUtils.h.

◆ TfPyThrowStopIteration() [1/2]

TF_API void TfPyThrowStopIteration ( const char *  msg)

Raises a Python StopIteration with the given error msg and throws a pxr_boost::python::error_already_set exception.

Callers must hold the GIL before calling this function.

◆ TfPyThrowStopIteration() [2/2]

void TfPyThrowStopIteration ( std::string const &  msg)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 76 of file pyUtils.h.

◆ TfPyThrowTypeError() [1/2]

TF_API void TfPyThrowTypeError ( const char *  msg)

Raises a Python TypeError with the given error msg and throws a pxr_boost::python::error_already_set exception.

Callers must hold the GIL before calling this function.

◆ TfPyThrowTypeError() [2/2]

void TfPyThrowTypeError ( std::string const &  msg)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 109 of file pyUtils.h.

◆ TfPyThrowValueError() [1/2]

TF_API void TfPyThrowValueError ( const char *  msg)

Raises a Python ValueError with the given error msg and throws a pxr_boost::python::error_already_set exception.

Callers must hold the GIL before calling this function.

◆ TfPyThrowValueError() [2/2]

void TfPyThrowValueError ( std::string const &  msg)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 98 of file pyUtils.h.

◆ TfPyUnsetenv()

TF_API bool TfPyUnsetenv ( const std::string &  name)

Remove an environment variable from os.environ.

This function is equivalent to

def PyUnsetenv(name):
try:
import os
if name in os.environ:
del os.environ[name]
return True
except:
return False

Calling this function without first initializing Python is an error and returns false.

Note that this function will import the os module, causing os.environ to be poputated. All modifications to the environment after os has been imported must be made with this function or TfUnsetenv if it important that they appear in os.environ.

◆ TfPyWrapOnce()

void TfPyWrapOnce ( std::function< void()> const &  wrapFunc)

Invokes wrapFunc to wrap type T if T is not already wrapped.

Executing wrapFunc must register T with boost python. Otherwise, wrapFunc may be executed more than once.

TfPyWrapOnce will acquire the GIL prior to invoking wrapFunc. Does not invoke wrapFunc if Python has not been initialized.

Definition at line 234 of file pyUtils.h.