pyUtils.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_BASE_TF_PY_UTILS_H
#define PXR_BASE_TF_PY_UTILS_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/base/tf/refPtr.h"
#include "pxr/base/tf/weakPtr.h"
#include "pxr/base/tf/diagnosticLite.h"
#include "pxr/base/tf/preprocessorUtilsLite.h"
#include "pxr/base/tf/pySafePython.h"
#include "pxr/base/tf/pyInterpreter.h"
#include "pxr/base/tf/pyLock.h"
#include "pxr/base/tf/api.h"
 
#include <functional>
#include <typeinfo>
#include <string>
#include <vector>
 
#include "pxr/external/boost/python/dict.hpp"
#include "pxr/external/boost/python/extract.hpp"
#include "pxr/external/boost/python/handle.hpp"
#include "pxr/external/boost/python/object.hpp"
#include "pxr/external/boost/python/type_id.hpp"
 
PXR_NAMESPACE_OPEN_SCOPE
 
#define TF_PY_REPR_PREFIX \
    std::string(TF_PP_STRINGIZE(MFB_PACKAGE_MODULE) ".")
 
TF_API bool TfPyIsInitialized();
 
TF_API void TfPyThrowIndexError(const char *msg);
 
inline void TfPyThrowIndexError(std::string const &msg)
{
    TfPyThrowIndexError(msg.c_str());
}
 
TF_API void TfPyThrowRuntimeError(const char *msg);
 
inline void TfPyThrowRuntimeError(std::string const &msg)
{
    TfPyThrowRuntimeError(msg.c_str());
}
 
TF_API void TfPyThrowStopIteration(const char *msg);
 
inline void TfPyThrowStopIteration(std::string const &msg)
{
    TfPyThrowStopIteration(msg.c_str());
}
 
TF_API void TfPyThrowKeyError(const char *msg);
 
inline void TfPyThrowKeyError(std::string const &msg)
{
    TfPyThrowKeyError(msg.c_str());
}
 
TF_API void TfPyThrowValueError(const char *msg);
 
inline void TfPyThrowValueError(std::string const &msg)
{
    TfPyThrowValueError(msg.c_str());
}
 
TF_API void TfPyThrowTypeError(const char *msg);
 
inline void TfPyThrowTypeError(std::string const &msg)
{
    TfPyThrowTypeError(msg.c_str());
}
 
TF_API bool TfPyIsNone(pxr_boost::python::object const &obj);
 
TF_API bool TfPyIsNone(pxr_boost::python::handle<> const &obj);
 
inline int
Tf_PyWeakrefGetRef(PyObject *ref, PyObject **pobj)
{
#if PY_VERSION_HEX >= 0x030D0000
    return PyWeakref_GetRef(ref, pobj);
#else
    PyObject *obj = PyWeakref_GetObject(ref);
    if (!obj) {
        // Not a weak reference; PyWeakref_GetObject has set an exception.
        // Leave *pobj alone: PyWeakref_GetRef does not specify its value on
        // error, so neither do we.
        return -1;
    }
    if (obj == Py_None) {
        // The referent has expired.  None itself is not weak-referenceable, so
        // this cannot be a live referent.
        *pobj = nullptr;
        return 0;
    }
    Py_INCREF(obj);
    *pobj = obj;
    return 1;
#endif
}
 
// Helper for \c TfPyObject().
TF_API void Tf_PyObjectError(bool printError);
 
template <typename T>
pxr_boost::python::object TfPyObject(T const &t, bool complainOnFailure = true) {
    // initialize python if it isn't already, so at least we can try to return
    // an object
    if (!TfPyIsInitialized()) {
        TF_CODING_ERROR("Called TfPyObject without python being initialized!");
        TfPyInitialize();
    }
 
    TfPyLock pyLock;
 
    // Will only be able to return objects which have been wrapped.
    // Returns None otherwise
    try {
        return pxr_boost::python::object(t);
    } catch (pxr_boost::python::error_already_set const &) {
        Tf_PyObjectError(complainOnFailure);
        return pxr_boost::python::object();
   }
}
 
inline
pxr_boost::python::object TfPyObject(PyObject* t, bool complainOnFailure = true) {
    TfPyLock pyLock;
    return pxr_boost::python::object(pxr_boost::python::handle<>(t));
}
 
TF_API std::string TfPyObjectRepr(pxr_boost::python::object const &t);
 
template <typename T>
std::string TfPyRepr(T const &t) {
    if (!TfPyIsInitialized())
        return "<python not initialized>";
    TfPyLock lock;
    return TfPyObjectRepr(TfPyObject(t));
}
 
template <typename T>
std::string TfPyRepr(const std::vector<T> &v) {
    std::string result("[");
    typename std::vector<T>::const_iterator i = v.begin();
    if (i != v.end()) {
        result += TfPyRepr(*i);
        ++i;
    }
    while (i != v.end()) {
        result += ", " + TfPyRepr(*i);
        ++i;
    }
    result += "]";
    return result;
}
 
TF_API
pxr_boost::python::object
TfPyEvaluate(
    std::string const &expr,
    pxr_boost::python::dict const &extraGlobals = pxr_boost::python::dict());
 
TF_API 
int64_t
TfPyNormalizeIndex(int64_t index, uint64_t size, bool throwError = false);
 
TF_API std::string TfPyGetClassName(pxr_boost::python::object const &obj);
 
 
TF_API pxr_boost::python::object
TfPyGetClassObject(std::type_info const &type);
 
template <typename T>
pxr_boost::python::object
TfPyGetClassObject() {
    return TfPyGetClassObject(typeid(T));
}
 
TF_API
void
Tf_PyWrapOnceImpl(pxr_boost::python::type_info const &,
                  std::function<void()> const&,
                  bool *);
 
template <typename T>
void
TfPyWrapOnce(std::function<void()> const &wrapFunc)
{
    // Don't try to wrap if python isn't initialized.
    if (!TfPyIsInitialized()) {
        return;
    }
 
    static bool isTypeWrapped = false;
    if (isTypeWrapped) {
        return;
    }
 
    Tf_PyWrapOnceImpl(pxr_boost::python::type_id<T>(), wrapFunc, &isTypeWrapped);
}
 
TF_API
void Tf_PyLoadScriptModule(std::string const &name);
 
template <class Map>
pxr_boost::python::dict TfPyCopyMapToDictionary(Map const &map) {
    TfPyLock lock;
    pxr_boost::python::dict d;
    for (typename Map::const_iterator i = map.begin(); i != map.end(); ++i)
        d[i->first] = i->second;
    return d;
}
 
template<class Seq>
pxr_boost::python::list TfPyCopySequenceToList(Seq const &seq) {
    TfPyLock lock;
    pxr_boost::python::list l;
    for (typename Seq::const_iterator i = seq.begin();
         i != seq.end(); ++i)
        l.append(*i);
    return l; 
}
 
template <class Seq>
pxr_boost::python::object TfPyCopySequenceToSet(Seq const &seq) {
    TfPyLock lock;
    pxr_boost::python::handle<> set{pxr_boost::python::allow_null(PySet_New(nullptr))};
    if (!set) {
        pxr_boost::python::throw_error_already_set();
    }
    for (auto const& item : seq) {
        pxr_boost::python::object obj(item);
        if (PySet_Add(set.get(), obj.ptr()) == -1) {
            pxr_boost::python::throw_error_already_set();
        }
    }
    return pxr_boost::python::object(set);
}
 
template<class Seq>
pxr_boost::python::tuple TfPyCopySequenceToTuple(Seq const &seq) {
    return pxr_boost::python::tuple(TfPyCopySequenceToList(seq));
}
 
TF_API
pxr_boost::python::object TfPyCopyBufferToByteArray(const char* buffer, size_t size);
 
TF_API
std::vector<std::string> TfPyGetTraceback();
 
TF_API
bool TfPySetenv(const std::string & name, const std::string & value);
 
TF_API
bool TfPyUnsetenv(const std::string & name);
 
// Private helper method to TfPyEvaluateAndExtract.
//
TF_API bool Tf_PyEvaluateWithErrorCheck(
    const std::string & expr, pxr_boost::python::object * obj);
 
template <typename T>
bool TfPyEvaluateAndExtract(const std::string & expr, T * t)
{
    if (expr.empty())
        return false;
 
    // Take the lock before doing anything with pxr_boost::python.
    TfPyLock lock;
 
    // Though TfPyEvaluate (called by Tf_PyEvaluateWithErroCheck) takes the
    // python lock, it is important that we lock before we initialize the 
    // pxr_boost::python::object, since it will increment and decrement ref counts 
    // outside of the call to TfPyEvaluate.
    pxr_boost::python::object obj;
    if (!Tf_PyEvaluateWithErrorCheck(expr, &obj))
        return false;
 
    pxr_boost::python::extract<T> extractor(obj);
 
    if (!extractor.check())
        return false;
 
    *t = extractor();
 
    return true;
}
 
TF_API
void TfPyPrintError();
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_BASE_TF_PY_UTILS_H