lldb/source/Plugins/ScriptInterpreter/Python/PythonDataObjects.h

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