1*061da546Spatrick //===-- PythonDataObjects.h--------------------------------------*- C++ -*-===// 2*061da546Spatrick // 3*061da546Spatrick // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4*061da546Spatrick // See https://llvm.org/LICENSE.txt for license information. 5*061da546Spatrick // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6*061da546Spatrick // 7*061da546Spatrick //===----------------------------------------------------------------------===// 8*061da546Spatrick 9*061da546Spatrick // 10*061da546Spatrick // !! FIXME FIXME FIXME !! 11*061da546Spatrick // 12*061da546Spatrick // Python APIs nearly all can return an exception. They do this 13*061da546Spatrick // by returning NULL, or -1, or some such value and setting 14*061da546Spatrick // the exception state with PyErr_Set*(). Exceptions must be 15*061da546Spatrick // handled before further python API functions are called. Failure 16*061da546Spatrick // to do so will result in asserts on debug builds of python. 17*061da546Spatrick // It will also sometimes, but not usually result in crashes of 18*061da546Spatrick // release builds. 19*061da546Spatrick // 20*061da546Spatrick // Nearly all the code in this header does not handle python exceptions 21*061da546Spatrick // correctly. It should all be converted to return Expected<> or 22*061da546Spatrick // Error types to capture the exception. 23*061da546Spatrick // 24*061da546Spatrick // Everything in this file except functions that return Error or 25*061da546Spatrick // Expected<> is considered deprecated and should not be 26*061da546Spatrick // used in new code. If you need to use it, fix it first. 27*061da546Spatrick // 28*061da546Spatrick // 29*061da546Spatrick // TODOs for this file 30*061da546Spatrick // 31*061da546Spatrick // * Make all methods safe for exceptions. 32*061da546Spatrick // 33*061da546Spatrick // * Eliminate method signatures that must translate exceptions into 34*061da546Spatrick // empty objects or NULLs. Almost everything here should return 35*061da546Spatrick // Expected<>. It should be acceptable for certain operations that 36*061da546Spatrick // can never fail to assert instead, such as the creation of 37*061da546Spatrick // PythonString from a string literal. 38*061da546Spatrick // 39*061da546Spatrick // * Elimintate Reset(), and make all non-default constructors private. 40*061da546Spatrick // Python objects should be created with Retain<> or Take<>, and they 41*061da546Spatrick // should be assigned with operator= 42*061da546Spatrick // 43*061da546Spatrick // * Eliminate default constructors, make python objects always 44*061da546Spatrick // nonnull, and use optionals where necessary. 45*061da546Spatrick // 46*061da546Spatrick 47*061da546Spatrick 48*061da546Spatrick #ifndef LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_PYTHONDATAOBJECTS_H 49*061da546Spatrick #define LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_PYTHONDATAOBJECTS_H 50*061da546Spatrick 51*061da546Spatrick #include "lldb/Host/Config.h" 52*061da546Spatrick 53*061da546Spatrick #if LLDB_ENABLE_PYTHON 54*061da546Spatrick 55*061da546Spatrick // LLDB Python header must be included first 56*061da546Spatrick #include "lldb-python.h" 57*061da546Spatrick 58*061da546Spatrick #include "lldb/Host/File.h" 59*061da546Spatrick #include "lldb/Utility/StructuredData.h" 60*061da546Spatrick 61*061da546Spatrick #include "llvm/ADT/ArrayRef.h" 62*061da546Spatrick 63*061da546Spatrick namespace lldb_private { 64*061da546Spatrick namespace python { 65*061da546Spatrick 66*061da546Spatrick class PythonObject; 67*061da546Spatrick class PythonBytes; 68*061da546Spatrick class PythonString; 69*061da546Spatrick class PythonList; 70*061da546Spatrick class PythonDictionary; 71*061da546Spatrick class PythonInteger; 72*061da546Spatrick class PythonException; 73*061da546Spatrick 74*061da546Spatrick class StructuredPythonObject : public StructuredData::Generic { 75*061da546Spatrick public: 76*061da546Spatrick StructuredPythonObject() : StructuredData::Generic() {} 77*061da546Spatrick 78*061da546Spatrick StructuredPythonObject(void *obj) : StructuredData::Generic(obj) { 79*061da546Spatrick Py_XINCREF(GetValue()); 80*061da546Spatrick } 81*061da546Spatrick 82*061da546Spatrick ~StructuredPythonObject() override { 83*061da546Spatrick if (Py_IsInitialized()) 84*061da546Spatrick Py_XDECREF(GetValue()); 85*061da546Spatrick SetValue(nullptr); 86*061da546Spatrick } 87*061da546Spatrick 88*061da546Spatrick bool IsValid() const override { return GetValue() && GetValue() != Py_None; } 89*061da546Spatrick 90*061da546Spatrick void Serialize(llvm::json::OStream &s) const override; 91*061da546Spatrick 92*061da546Spatrick private: 93*061da546Spatrick DISALLOW_COPY_AND_ASSIGN(StructuredPythonObject); 94*061da546Spatrick }; 95*061da546Spatrick 96*061da546Spatrick enum class PyObjectType { 97*061da546Spatrick Unknown, 98*061da546Spatrick None, 99*061da546Spatrick Boolean, 100*061da546Spatrick Integer, 101*061da546Spatrick Dictionary, 102*061da546Spatrick List, 103*061da546Spatrick String, 104*061da546Spatrick Bytes, 105*061da546Spatrick ByteArray, 106*061da546Spatrick Module, 107*061da546Spatrick Callable, 108*061da546Spatrick Tuple, 109*061da546Spatrick File 110*061da546Spatrick }; 111*061da546Spatrick 112*061da546Spatrick enum class PyRefType { 113*061da546Spatrick Borrowed, // We are not given ownership of the incoming PyObject. 114*061da546Spatrick // We cannot safely hold it without calling Py_INCREF. 115*061da546Spatrick Owned // We have ownership of the incoming PyObject. We should 116*061da546Spatrick // not call Py_INCREF. 117*061da546Spatrick }; 118*061da546Spatrick 119*061da546Spatrick 120*061da546Spatrick // Take a reference that you already own, and turn it into 121*061da546Spatrick // a PythonObject. 122*061da546Spatrick // 123*061da546Spatrick // Most python API methods will return a +1 reference 124*061da546Spatrick // if they succeed or NULL if and only if 125*061da546Spatrick // they set an exception. Use this to collect such return 126*061da546Spatrick // values, after checking for NULL. 127*061da546Spatrick // 128*061da546Spatrick // If T is not just PythonObject, then obj must be already be 129*061da546Spatrick // checked to be of the correct type. 130*061da546Spatrick template <typename T> T Take(PyObject *obj) { 131*061da546Spatrick assert(obj); 132*061da546Spatrick assert(!PyErr_Occurred()); 133*061da546Spatrick T thing(PyRefType::Owned, obj); 134*061da546Spatrick assert(thing.IsValid()); 135*061da546Spatrick return thing; 136*061da546Spatrick } 137*061da546Spatrick 138*061da546Spatrick // Retain a reference you have borrowed, and turn it into 139*061da546Spatrick // a PythonObject. 140*061da546Spatrick // 141*061da546Spatrick // A minority of python APIs return a borrowed reference 142*061da546Spatrick // instead of a +1. They will also return NULL if and only 143*061da546Spatrick // if they set an exception. Use this to collect such return 144*061da546Spatrick // values, after checking for NULL. 145*061da546Spatrick // 146*061da546Spatrick // If T is not just PythonObject, then obj must be already be 147*061da546Spatrick // checked to be of the correct type. 148*061da546Spatrick template <typename T> T Retain(PyObject *obj) { 149*061da546Spatrick assert(obj); 150*061da546Spatrick assert(!PyErr_Occurred()); 151*061da546Spatrick T thing(PyRefType::Borrowed, obj); 152*061da546Spatrick assert(thing.IsValid()); 153*061da546Spatrick return thing; 154*061da546Spatrick } 155*061da546Spatrick 156*061da546Spatrick // This class can be used like a utility function to convert from 157*061da546Spatrick // a llvm-friendly Twine into a null-terminated const char *, 158*061da546Spatrick // which is the form python C APIs want their strings in. 159*061da546Spatrick // 160*061da546Spatrick // Example: 161*061da546Spatrick // const llvm::Twine &some_twine; 162*061da546Spatrick // PyFoo_Bar(x, y, z, NullTerminated(some_twine)); 163*061da546Spatrick // 164*061da546Spatrick // Why a class instead of a function? If the twine isn't already null 165*061da546Spatrick // terminated, it will need a temporary buffer to copy the string 166*061da546Spatrick // into. We need that buffer to stick around for the lifetime of the 167*061da546Spatrick // statement. 168*061da546Spatrick class NullTerminated { 169*061da546Spatrick const char *str; 170*061da546Spatrick llvm::SmallString<32> storage; 171*061da546Spatrick 172*061da546Spatrick public: 173*061da546Spatrick NullTerminated(const llvm::Twine &twine) { 174*061da546Spatrick llvm::StringRef ref = twine.toNullTerminatedStringRef(storage); 175*061da546Spatrick str = ref.begin(); 176*061da546Spatrick } 177*061da546Spatrick operator const char *() { return str; } 178*061da546Spatrick }; 179*061da546Spatrick 180*061da546Spatrick inline llvm::Error nullDeref() { 181*061da546Spatrick return llvm::createStringError(llvm::inconvertibleErrorCode(), 182*061da546Spatrick "A NULL PyObject* was dereferenced"); 183*061da546Spatrick } 184*061da546Spatrick 185*061da546Spatrick inline llvm::Error exception(const char *s = nullptr) { 186*061da546Spatrick return llvm::make_error<PythonException>(s); 187*061da546Spatrick } 188*061da546Spatrick 189*061da546Spatrick inline llvm::Error keyError() { 190*061da546Spatrick return llvm::createStringError(llvm::inconvertibleErrorCode(), 191*061da546Spatrick "key not in dict"); 192*061da546Spatrick } 193*061da546Spatrick 194*061da546Spatrick #if PY_MAJOR_VERSION < 3 195*061da546Spatrick // The python 2 API declares some arguments as char* that should 196*061da546Spatrick // be const char *, but it doesn't actually modify them. 197*061da546Spatrick inline char *py2_const_cast(const char *s) { return const_cast<char *>(s); } 198*061da546Spatrick #else 199*061da546Spatrick inline const char *py2_const_cast(const char *s) { return s; } 200*061da546Spatrick #endif 201*061da546Spatrick 202*061da546Spatrick enum class PyInitialValue { Invalid, Empty }; 203*061da546Spatrick 204*061da546Spatrick template <typename T, typename Enable = void> struct PythonFormat; 205*061da546Spatrick 206*061da546Spatrick template <> struct PythonFormat<unsigned long long> { 207*061da546Spatrick static constexpr char format = 'K'; 208*061da546Spatrick static auto get(unsigned long long value) { return value; } 209*061da546Spatrick }; 210*061da546Spatrick 211*061da546Spatrick template <> struct PythonFormat<long long> { 212*061da546Spatrick static constexpr char format = 'L'; 213*061da546Spatrick static auto get(long long value) { return value; } 214*061da546Spatrick }; 215*061da546Spatrick 216*061da546Spatrick template <> struct PythonFormat<PyObject *> { 217*061da546Spatrick static constexpr char format = 'O'; 218*061da546Spatrick static auto get(PyObject *value) { return value; } 219*061da546Spatrick }; 220*061da546Spatrick 221*061da546Spatrick template <typename T> 222*061da546Spatrick struct PythonFormat< 223*061da546Spatrick T, typename std::enable_if<std::is_base_of<PythonObject, T>::value>::type> { 224*061da546Spatrick static constexpr char format = 'O'; 225*061da546Spatrick static auto get(const T &value) { return value.get(); } 226*061da546Spatrick }; 227*061da546Spatrick 228*061da546Spatrick class PythonObject { 229*061da546Spatrick public: 230*061da546Spatrick PythonObject() : m_py_obj(nullptr) {} 231*061da546Spatrick 232*061da546Spatrick PythonObject(PyRefType type, PyObject *py_obj) { 233*061da546Spatrick m_py_obj = py_obj; 234*061da546Spatrick // If this is a borrowed reference, we need to convert it to 235*061da546Spatrick // an owned reference by incrementing it. If it is an owned 236*061da546Spatrick // reference (for example the caller allocated it with PyDict_New() 237*061da546Spatrick // then we must *not* increment it. 238*061da546Spatrick if (m_py_obj && Py_IsInitialized() && type == PyRefType::Borrowed) 239*061da546Spatrick Py_XINCREF(m_py_obj); 240*061da546Spatrick } 241*061da546Spatrick 242*061da546Spatrick PythonObject(const PythonObject &rhs) 243*061da546Spatrick : PythonObject(PyRefType::Borrowed, rhs.m_py_obj) {} 244*061da546Spatrick 245*061da546Spatrick PythonObject(PythonObject &&rhs) { 246*061da546Spatrick m_py_obj = rhs.m_py_obj; 247*061da546Spatrick rhs.m_py_obj = nullptr; 248*061da546Spatrick } 249*061da546Spatrick 250*061da546Spatrick ~PythonObject() { Reset(); } 251*061da546Spatrick 252*061da546Spatrick void Reset() { 253*061da546Spatrick if (m_py_obj && Py_IsInitialized()) 254*061da546Spatrick Py_DECREF(m_py_obj); 255*061da546Spatrick m_py_obj = nullptr; 256*061da546Spatrick } 257*061da546Spatrick 258*061da546Spatrick void Dump() const { 259*061da546Spatrick if (m_py_obj) 260*061da546Spatrick _PyObject_Dump(m_py_obj); 261*061da546Spatrick else 262*061da546Spatrick puts("NULL"); 263*061da546Spatrick } 264*061da546Spatrick 265*061da546Spatrick void Dump(Stream &strm) const; 266*061da546Spatrick 267*061da546Spatrick PyObject *get() const { return m_py_obj; } 268*061da546Spatrick 269*061da546Spatrick PyObject *release() { 270*061da546Spatrick PyObject *result = m_py_obj; 271*061da546Spatrick m_py_obj = nullptr; 272*061da546Spatrick return result; 273*061da546Spatrick } 274*061da546Spatrick 275*061da546Spatrick PythonObject &operator=(PythonObject other) { 276*061da546Spatrick Reset(); 277*061da546Spatrick m_py_obj = std::exchange(other.m_py_obj, nullptr); 278*061da546Spatrick return *this; 279*061da546Spatrick } 280*061da546Spatrick 281*061da546Spatrick PyObjectType GetObjectType() const; 282*061da546Spatrick 283*061da546Spatrick PythonString Repr() const; 284*061da546Spatrick 285*061da546Spatrick PythonString Str() const; 286*061da546Spatrick 287*061da546Spatrick static PythonObject ResolveNameWithDictionary(llvm::StringRef name, 288*061da546Spatrick const PythonDictionary &dict); 289*061da546Spatrick 290*061da546Spatrick template <typename T> 291*061da546Spatrick static T ResolveNameWithDictionary(llvm::StringRef name, 292*061da546Spatrick const PythonDictionary &dict) { 293*061da546Spatrick return ResolveNameWithDictionary(name, dict).AsType<T>(); 294*061da546Spatrick } 295*061da546Spatrick 296*061da546Spatrick PythonObject ResolveName(llvm::StringRef name) const; 297*061da546Spatrick 298*061da546Spatrick template <typename T> T ResolveName(llvm::StringRef name) const { 299*061da546Spatrick return ResolveName(name).AsType<T>(); 300*061da546Spatrick } 301*061da546Spatrick 302*061da546Spatrick bool HasAttribute(llvm::StringRef attribute) const; 303*061da546Spatrick 304*061da546Spatrick PythonObject GetAttributeValue(llvm::StringRef attribute) const; 305*061da546Spatrick 306*061da546Spatrick bool IsNone() const { return m_py_obj == Py_None; } 307*061da546Spatrick 308*061da546Spatrick bool IsValid() const { return m_py_obj != nullptr; } 309*061da546Spatrick 310*061da546Spatrick bool IsAllocated() const { return IsValid() && !IsNone(); } 311*061da546Spatrick 312*061da546Spatrick explicit operator bool() const { return IsValid() && !IsNone(); } 313*061da546Spatrick 314*061da546Spatrick template <typename T> T AsType() const { 315*061da546Spatrick if (!T::Check(m_py_obj)) 316*061da546Spatrick return T(); 317*061da546Spatrick return T(PyRefType::Borrowed, m_py_obj); 318*061da546Spatrick } 319*061da546Spatrick 320*061da546Spatrick StructuredData::ObjectSP CreateStructuredObject() const; 321*061da546Spatrick 322*061da546Spatrick public: 323*061da546Spatrick template <typename... T> 324*061da546Spatrick llvm::Expected<PythonObject> CallMethod(const char *name, 325*061da546Spatrick const T &... t) const { 326*061da546Spatrick const char format[] = {'(', PythonFormat<T>::format..., ')', 0}; 327*061da546Spatrick PyObject *obj = 328*061da546Spatrick PyObject_CallMethod(m_py_obj, py2_const_cast(name), 329*061da546Spatrick py2_const_cast(format), PythonFormat<T>::get(t)...); 330*061da546Spatrick if (!obj) 331*061da546Spatrick return exception(); 332*061da546Spatrick return python::Take<PythonObject>(obj); 333*061da546Spatrick } 334*061da546Spatrick 335*061da546Spatrick template <typename... T> 336*061da546Spatrick llvm::Expected<PythonObject> Call(const T &... t) const { 337*061da546Spatrick const char format[] = {'(', PythonFormat<T>::format..., ')', 0}; 338*061da546Spatrick PyObject *obj = PyObject_CallFunction(m_py_obj, py2_const_cast(format), 339*061da546Spatrick PythonFormat<T>::get(t)...); 340*061da546Spatrick if (!obj) 341*061da546Spatrick return exception(); 342*061da546Spatrick return python::Take<PythonObject>(obj); 343*061da546Spatrick } 344*061da546Spatrick 345*061da546Spatrick llvm::Expected<PythonObject> GetAttribute(const llvm::Twine &name) const { 346*061da546Spatrick if (!m_py_obj) 347*061da546Spatrick return nullDeref(); 348*061da546Spatrick PyObject *obj = PyObject_GetAttrString(m_py_obj, NullTerminated(name)); 349*061da546Spatrick if (!obj) 350*061da546Spatrick return exception(); 351*061da546Spatrick return python::Take<PythonObject>(obj); 352*061da546Spatrick } 353*061da546Spatrick 354*061da546Spatrick llvm::Expected<bool> IsTrue() { 355*061da546Spatrick if (!m_py_obj) 356*061da546Spatrick return nullDeref(); 357*061da546Spatrick int r = PyObject_IsTrue(m_py_obj); 358*061da546Spatrick if (r < 0) 359*061da546Spatrick return exception(); 360*061da546Spatrick return !!r; 361*061da546Spatrick } 362*061da546Spatrick 363*061da546Spatrick llvm::Expected<long long> AsLongLong() { 364*061da546Spatrick if (!m_py_obj) 365*061da546Spatrick return nullDeref(); 366*061da546Spatrick assert(!PyErr_Occurred()); 367*061da546Spatrick long long r = PyLong_AsLongLong(m_py_obj); 368*061da546Spatrick if (PyErr_Occurred()) 369*061da546Spatrick return exception(); 370*061da546Spatrick return r; 371*061da546Spatrick } 372*061da546Spatrick 373*061da546Spatrick llvm::Expected<bool> IsInstance(const PythonObject &cls) { 374*061da546Spatrick if (!m_py_obj || !cls.IsValid()) 375*061da546Spatrick return nullDeref(); 376*061da546Spatrick int r = PyObject_IsInstance(m_py_obj, cls.get()); 377*061da546Spatrick if (r < 0) 378*061da546Spatrick return exception(); 379*061da546Spatrick return !!r; 380*061da546Spatrick } 381*061da546Spatrick 382*061da546Spatrick protected: 383*061da546Spatrick PyObject *m_py_obj; 384*061da546Spatrick }; 385*061da546Spatrick 386*061da546Spatrick 387*061da546Spatrick // This is why C++ needs monads. 388*061da546Spatrick template <typename T> llvm::Expected<T> As(llvm::Expected<PythonObject> &&obj) { 389*061da546Spatrick if (!obj) 390*061da546Spatrick return obj.takeError(); 391*061da546Spatrick if (!T::Check(obj.get().get())) 392*061da546Spatrick return llvm::createStringError(llvm::inconvertibleErrorCode(), 393*061da546Spatrick "type error"); 394*061da546Spatrick return T(PyRefType::Borrowed, std::move(obj.get().get())); 395*061da546Spatrick } 396*061da546Spatrick 397*061da546Spatrick template <> llvm::Expected<bool> As<bool>(llvm::Expected<PythonObject> &&obj); 398*061da546Spatrick 399*061da546Spatrick template <> 400*061da546Spatrick llvm::Expected<long long> As<long long>(llvm::Expected<PythonObject> &&obj); 401*061da546Spatrick 402*061da546Spatrick template <> 403*061da546Spatrick llvm::Expected<std::string> As<std::string>(llvm::Expected<PythonObject> &&obj); 404*061da546Spatrick 405*061da546Spatrick 406*061da546Spatrick template <class T> class TypedPythonObject : public PythonObject { 407*061da546Spatrick public: 408*061da546Spatrick // override to perform implicit type conversions on Reset 409*061da546Spatrick // This can be eliminated once we drop python 2 support. 410*061da546Spatrick static void Convert(PyRefType &type, PyObject *&py_obj) {} 411*061da546Spatrick 412*061da546Spatrick TypedPythonObject(PyRefType type, PyObject *py_obj) { 413*061da546Spatrick if (!py_obj) 414*061da546Spatrick return; 415*061da546Spatrick T::Convert(type, py_obj); 416*061da546Spatrick if (T::Check(py_obj)) 417*061da546Spatrick PythonObject::operator=(PythonObject(type, py_obj)); 418*061da546Spatrick else if (type == PyRefType::Owned) 419*061da546Spatrick Py_DECREF(py_obj); 420*061da546Spatrick } 421*061da546Spatrick 422*061da546Spatrick TypedPythonObject() {} 423*061da546Spatrick }; 424*061da546Spatrick 425*061da546Spatrick class PythonBytes : public TypedPythonObject<PythonBytes> { 426*061da546Spatrick public: 427*061da546Spatrick using TypedPythonObject::TypedPythonObject; 428*061da546Spatrick explicit PythonBytes(llvm::ArrayRef<uint8_t> bytes); 429*061da546Spatrick PythonBytes(const uint8_t *bytes, size_t length); 430*061da546Spatrick 431*061da546Spatrick static bool Check(PyObject *py_obj); 432*061da546Spatrick 433*061da546Spatrick llvm::ArrayRef<uint8_t> GetBytes() const; 434*061da546Spatrick 435*061da546Spatrick size_t GetSize() const; 436*061da546Spatrick 437*061da546Spatrick void SetBytes(llvm::ArrayRef<uint8_t> stringbytes); 438*061da546Spatrick 439*061da546Spatrick StructuredData::StringSP CreateStructuredString() const; 440*061da546Spatrick }; 441*061da546Spatrick 442*061da546Spatrick class PythonByteArray : public TypedPythonObject<PythonByteArray> { 443*061da546Spatrick public: 444*061da546Spatrick using TypedPythonObject::TypedPythonObject; 445*061da546Spatrick explicit PythonByteArray(llvm::ArrayRef<uint8_t> bytes); 446*061da546Spatrick PythonByteArray(const uint8_t *bytes, size_t length); 447*061da546Spatrick PythonByteArray(const PythonBytes &object); 448*061da546Spatrick 449*061da546Spatrick static bool Check(PyObject *py_obj); 450*061da546Spatrick 451*061da546Spatrick llvm::ArrayRef<uint8_t> GetBytes() const; 452*061da546Spatrick 453*061da546Spatrick size_t GetSize() const; 454*061da546Spatrick 455*061da546Spatrick void SetBytes(llvm::ArrayRef<uint8_t> stringbytes); 456*061da546Spatrick 457*061da546Spatrick StructuredData::StringSP CreateStructuredString() const; 458*061da546Spatrick }; 459*061da546Spatrick 460*061da546Spatrick class PythonString : public TypedPythonObject<PythonString> { 461*061da546Spatrick public: 462*061da546Spatrick using TypedPythonObject::TypedPythonObject; 463*061da546Spatrick static llvm::Expected<PythonString> FromUTF8(llvm::StringRef string); 464*061da546Spatrick 465*061da546Spatrick PythonString() : TypedPythonObject() {} // MSVC requires this for some reason 466*061da546Spatrick 467*061da546Spatrick explicit PythonString(llvm::StringRef string); // safe, null on error 468*061da546Spatrick 469*061da546Spatrick static bool Check(PyObject *py_obj); 470*061da546Spatrick static void Convert(PyRefType &type, PyObject *&py_obj); 471*061da546Spatrick 472*061da546Spatrick llvm::StringRef GetString() const; // safe, empty string on error 473*061da546Spatrick 474*061da546Spatrick llvm::Expected<llvm::StringRef> AsUTF8() const; 475*061da546Spatrick 476*061da546Spatrick size_t GetSize() const; 477*061da546Spatrick 478*061da546Spatrick void SetString(llvm::StringRef string); // safe, null on error 479*061da546Spatrick 480*061da546Spatrick StructuredData::StringSP CreateStructuredString() const; 481*061da546Spatrick }; 482*061da546Spatrick 483*061da546Spatrick class PythonInteger : public TypedPythonObject<PythonInteger> { 484*061da546Spatrick public: 485*061da546Spatrick using TypedPythonObject::TypedPythonObject; 486*061da546Spatrick 487*061da546Spatrick PythonInteger() : TypedPythonObject() {} // MSVC requires this for some reason 488*061da546Spatrick 489*061da546Spatrick explicit PythonInteger(int64_t value); 490*061da546Spatrick 491*061da546Spatrick static bool Check(PyObject *py_obj); 492*061da546Spatrick static void Convert(PyRefType &type, PyObject *&py_obj); 493*061da546Spatrick 494*061da546Spatrick int64_t GetInteger() const; 495*061da546Spatrick 496*061da546Spatrick void SetInteger(int64_t value); 497*061da546Spatrick 498*061da546Spatrick StructuredData::IntegerSP CreateStructuredInteger() const; 499*061da546Spatrick }; 500*061da546Spatrick 501*061da546Spatrick class PythonBoolean : public TypedPythonObject<PythonBoolean> { 502*061da546Spatrick public: 503*061da546Spatrick using TypedPythonObject::TypedPythonObject; 504*061da546Spatrick 505*061da546Spatrick explicit PythonBoolean(bool value); 506*061da546Spatrick 507*061da546Spatrick static bool Check(PyObject *py_obj); 508*061da546Spatrick 509*061da546Spatrick bool GetValue() const; 510*061da546Spatrick 511*061da546Spatrick void SetValue(bool value); 512*061da546Spatrick 513*061da546Spatrick StructuredData::BooleanSP CreateStructuredBoolean() const; 514*061da546Spatrick }; 515*061da546Spatrick 516*061da546Spatrick class PythonList : public TypedPythonObject<PythonList> { 517*061da546Spatrick public: 518*061da546Spatrick using TypedPythonObject::TypedPythonObject; 519*061da546Spatrick 520*061da546Spatrick PythonList() : TypedPythonObject() {} // MSVC requires this for some reason 521*061da546Spatrick 522*061da546Spatrick explicit PythonList(PyInitialValue value); 523*061da546Spatrick explicit PythonList(int list_size); 524*061da546Spatrick 525*061da546Spatrick static bool Check(PyObject *py_obj); 526*061da546Spatrick 527*061da546Spatrick uint32_t GetSize() const; 528*061da546Spatrick 529*061da546Spatrick PythonObject GetItemAtIndex(uint32_t index) const; 530*061da546Spatrick 531*061da546Spatrick void SetItemAtIndex(uint32_t index, const PythonObject &object); 532*061da546Spatrick 533*061da546Spatrick void AppendItem(const PythonObject &object); 534*061da546Spatrick 535*061da546Spatrick StructuredData::ArraySP CreateStructuredArray() const; 536*061da546Spatrick }; 537*061da546Spatrick 538*061da546Spatrick class PythonTuple : public TypedPythonObject<PythonTuple> { 539*061da546Spatrick public: 540*061da546Spatrick using TypedPythonObject::TypedPythonObject; 541*061da546Spatrick 542*061da546Spatrick explicit PythonTuple(PyInitialValue value); 543*061da546Spatrick explicit PythonTuple(int tuple_size); 544*061da546Spatrick PythonTuple(std::initializer_list<PythonObject> objects); 545*061da546Spatrick PythonTuple(std::initializer_list<PyObject *> objects); 546*061da546Spatrick 547*061da546Spatrick static bool Check(PyObject *py_obj); 548*061da546Spatrick 549*061da546Spatrick uint32_t GetSize() const; 550*061da546Spatrick 551*061da546Spatrick PythonObject GetItemAtIndex(uint32_t index) const; 552*061da546Spatrick 553*061da546Spatrick void SetItemAtIndex(uint32_t index, const PythonObject &object); 554*061da546Spatrick 555*061da546Spatrick StructuredData::ArraySP CreateStructuredArray() const; 556*061da546Spatrick }; 557*061da546Spatrick 558*061da546Spatrick class PythonDictionary : public TypedPythonObject<PythonDictionary> { 559*061da546Spatrick public: 560*061da546Spatrick using TypedPythonObject::TypedPythonObject; 561*061da546Spatrick 562*061da546Spatrick PythonDictionary() : TypedPythonObject() {} // MSVC requires this for some reason 563*061da546Spatrick 564*061da546Spatrick explicit PythonDictionary(PyInitialValue value); 565*061da546Spatrick 566*061da546Spatrick static bool Check(PyObject *py_obj); 567*061da546Spatrick 568*061da546Spatrick uint32_t GetSize() const; 569*061da546Spatrick 570*061da546Spatrick PythonList GetKeys() const; 571*061da546Spatrick 572*061da546Spatrick PythonObject GetItemForKey(const PythonObject &key) const; // DEPRECATED 573*061da546Spatrick void SetItemForKey(const PythonObject &key, 574*061da546Spatrick const PythonObject &value); // DEPRECATED 575*061da546Spatrick 576*061da546Spatrick llvm::Expected<PythonObject> GetItem(const PythonObject &key) const; 577*061da546Spatrick llvm::Expected<PythonObject> GetItem(const llvm::Twine &key) const; 578*061da546Spatrick llvm::Error SetItem(const PythonObject &key, const PythonObject &value) const; 579*061da546Spatrick llvm::Error SetItem(const llvm::Twine &key, const PythonObject &value) const; 580*061da546Spatrick 581*061da546Spatrick StructuredData::DictionarySP CreateStructuredDictionary() const; 582*061da546Spatrick }; 583*061da546Spatrick 584*061da546Spatrick class PythonModule : public TypedPythonObject<PythonModule> { 585*061da546Spatrick public: 586*061da546Spatrick using TypedPythonObject::TypedPythonObject; 587*061da546Spatrick 588*061da546Spatrick static bool Check(PyObject *py_obj); 589*061da546Spatrick 590*061da546Spatrick static PythonModule BuiltinsModule(); 591*061da546Spatrick 592*061da546Spatrick static PythonModule MainModule(); 593*061da546Spatrick 594*061da546Spatrick static PythonModule AddModule(llvm::StringRef module); 595*061da546Spatrick 596*061da546Spatrick // safe, returns invalid on error; 597*061da546Spatrick static PythonModule ImportModule(llvm::StringRef name) { 598*061da546Spatrick std::string s = name; 599*061da546Spatrick auto mod = Import(s.c_str()); 600*061da546Spatrick if (!mod) { 601*061da546Spatrick llvm::consumeError(mod.takeError()); 602*061da546Spatrick return PythonModule(); 603*061da546Spatrick } 604*061da546Spatrick return std::move(mod.get()); 605*061da546Spatrick } 606*061da546Spatrick 607*061da546Spatrick static llvm::Expected<PythonModule> Import(const llvm::Twine &name); 608*061da546Spatrick 609*061da546Spatrick llvm::Expected<PythonObject> Get(const llvm::Twine &name); 610*061da546Spatrick 611*061da546Spatrick PythonDictionary GetDictionary() const; 612*061da546Spatrick }; 613*061da546Spatrick 614*061da546Spatrick class PythonCallable : public TypedPythonObject<PythonCallable> { 615*061da546Spatrick public: 616*061da546Spatrick using TypedPythonObject::TypedPythonObject; 617*061da546Spatrick 618*061da546Spatrick struct ArgInfo { 619*061da546Spatrick /* the largest number of positional arguments this callable 620*061da546Spatrick * can accept, or UNBOUNDED, ie UINT_MAX if it's a varargs 621*061da546Spatrick * function and can accept an arbitrary number */ 622*061da546Spatrick unsigned max_positional_args; 623*061da546Spatrick static constexpr unsigned UNBOUNDED = UINT_MAX; // FIXME c++17 inline 624*061da546Spatrick }; 625*061da546Spatrick 626*061da546Spatrick static bool Check(PyObject *py_obj); 627*061da546Spatrick 628*061da546Spatrick llvm::Expected<ArgInfo> GetArgInfo() const; 629*061da546Spatrick 630*061da546Spatrick PythonObject operator()(); 631*061da546Spatrick 632*061da546Spatrick PythonObject operator()(std::initializer_list<PyObject *> args); 633*061da546Spatrick 634*061da546Spatrick PythonObject operator()(std::initializer_list<PythonObject> args); 635*061da546Spatrick 636*061da546Spatrick template <typename Arg, typename... Args> 637*061da546Spatrick PythonObject operator()(const Arg &arg, Args... args) { 638*061da546Spatrick return operator()({arg, args...}); 639*061da546Spatrick } 640*061da546Spatrick }; 641*061da546Spatrick 642*061da546Spatrick class PythonFile : public TypedPythonObject<PythonFile> { 643*061da546Spatrick public: 644*061da546Spatrick using TypedPythonObject::TypedPythonObject; 645*061da546Spatrick 646*061da546Spatrick PythonFile() : TypedPythonObject() {} // MSVC requires this for some reason 647*061da546Spatrick 648*061da546Spatrick static bool Check(PyObject *py_obj); 649*061da546Spatrick 650*061da546Spatrick static llvm::Expected<PythonFile> FromFile(File &file, 651*061da546Spatrick const char *mode = nullptr); 652*061da546Spatrick 653*061da546Spatrick llvm::Expected<lldb::FileSP> ConvertToFile(bool borrowed = false); 654*061da546Spatrick llvm::Expected<lldb::FileSP> 655*061da546Spatrick ConvertToFileForcingUseOfScriptingIOMethods(bool borrowed = false); 656*061da546Spatrick }; 657*061da546Spatrick 658*061da546Spatrick class PythonException : public llvm::ErrorInfo<PythonException> { 659*061da546Spatrick private: 660*061da546Spatrick PyObject *m_exception_type, *m_exception, *m_traceback; 661*061da546Spatrick PyObject *m_repr_bytes; 662*061da546Spatrick 663*061da546Spatrick public: 664*061da546Spatrick static char ID; 665*061da546Spatrick const char *toCString() const; 666*061da546Spatrick PythonException(const char *caller = nullptr); 667*061da546Spatrick void Restore(); 668*061da546Spatrick ~PythonException(); 669*061da546Spatrick void log(llvm::raw_ostream &OS) const override; 670*061da546Spatrick std::error_code convertToErrorCode() const override; 671*061da546Spatrick bool Matches(PyObject *exc) const; 672*061da546Spatrick std::string ReadBacktrace() const; 673*061da546Spatrick }; 674*061da546Spatrick 675*061da546Spatrick // This extracts the underlying T out of an Expected<T> and returns it. 676*061da546Spatrick // If the Expected is an Error instead of a T, that error will be converted 677*061da546Spatrick // into a python exception, and this will return a default-constructed T. 678*061da546Spatrick // 679*061da546Spatrick // This is appropriate for use right at the boundary of python calling into 680*061da546Spatrick // C++, such as in a SWIG typemap. In such a context you should simply 681*061da546Spatrick // check if the returned T is valid, and if it is, return a NULL back 682*061da546Spatrick // to python. This will result in the Error being raised as an exception 683*061da546Spatrick // from python code's point of view. 684*061da546Spatrick // 685*061da546Spatrick // For example: 686*061da546Spatrick // ``` 687*061da546Spatrick // Expected<Foo *> efoop = some_cpp_function(); 688*061da546Spatrick // Foo *foop = unwrapOrSetPythonException(efoop); 689*061da546Spatrick // if (!foop) 690*061da546Spatrick // return NULL; 691*061da546Spatrick // do_something(*foop); 692*061da546Spatrick // 693*061da546Spatrick // If the Error returned was itself created because a python exception was 694*061da546Spatrick // raised when C++ code called into python, then the original exception 695*061da546Spatrick // will be restored. Otherwise a simple string exception will be raised. 696*061da546Spatrick template <typename T> T unwrapOrSetPythonException(llvm::Expected<T> expected) { 697*061da546Spatrick if (expected) 698*061da546Spatrick return expected.get(); 699*061da546Spatrick llvm::handleAllErrors( 700*061da546Spatrick expected.takeError(), [](PythonException &E) { E.Restore(); }, 701*061da546Spatrick [](const llvm::ErrorInfoBase &E) { 702*061da546Spatrick PyErr_SetString(PyExc_Exception, E.message().c_str()); 703*061da546Spatrick }); 704*061da546Spatrick return T(); 705*061da546Spatrick } 706*061da546Spatrick 707*061da546Spatrick // This is only here to help incrementally migrate old, exception-unsafe 708*061da546Spatrick // code. 709*061da546Spatrick template <typename T> T unwrapIgnoringErrors(llvm::Expected<T> expected) { 710*061da546Spatrick if (expected) 711*061da546Spatrick return std::move(expected.get()); 712*061da546Spatrick llvm::consumeError(expected.takeError()); 713*061da546Spatrick return T(); 714*061da546Spatrick } 715*061da546Spatrick 716*061da546Spatrick llvm::Expected<PythonObject> runStringOneLine(const llvm::Twine &string, 717*061da546Spatrick const PythonDictionary &globals, 718*061da546Spatrick const PythonDictionary &locals); 719*061da546Spatrick 720*061da546Spatrick llvm::Expected<PythonObject> runStringMultiLine(const llvm::Twine &string, 721*061da546Spatrick const PythonDictionary &globals, 722*061da546Spatrick const PythonDictionary &locals); 723*061da546Spatrick 724*061da546Spatrick // Sometimes the best way to interact with a python interpreter is 725*061da546Spatrick // to run some python code. You construct a PythonScript with 726*061da546Spatrick // script string. The script assigns some function to `_function_` 727*061da546Spatrick // and you get a C++ callable object that calls the python function. 728*061da546Spatrick // 729*061da546Spatrick // Example: 730*061da546Spatrick // 731*061da546Spatrick // const char script[] = R"( 732*061da546Spatrick // def main(x, y): 733*061da546Spatrick // .... 734*061da546Spatrick // )"; 735*061da546Spatrick // 736*061da546Spatrick // Expected<PythonObject> cpp_foo_wrapper(PythonObject x, PythonObject y) { 737*061da546Spatrick // // no need to synchronize access to this global, we already have the GIL 738*061da546Spatrick // static PythonScript foo(script) 739*061da546Spatrick // return foo(x, y); 740*061da546Spatrick // } 741*061da546Spatrick class PythonScript { 742*061da546Spatrick const char *script; 743*061da546Spatrick PythonCallable function; 744*061da546Spatrick 745*061da546Spatrick llvm::Error Init(); 746*061da546Spatrick 747*061da546Spatrick public: 748*061da546Spatrick PythonScript(const char *script) : script(script), function() {} 749*061da546Spatrick 750*061da546Spatrick template <typename... Args> 751*061da546Spatrick llvm::Expected<PythonObject> operator()(Args &&... args) { 752*061da546Spatrick if (llvm::Error error = Init()) 753*061da546Spatrick return std::move(error); 754*061da546Spatrick return function.Call(std::forward<Args>(args)...); 755*061da546Spatrick } 756*061da546Spatrick }; 757*061da546Spatrick 758*061da546Spatrick } // namespace python 759*061da546Spatrick } // namespace lldb_private 760*061da546Spatrick 761*061da546Spatrick #endif 762*061da546Spatrick 763*061da546Spatrick #endif // LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_PYTHONDATAOBJECTS_H 764