xref: /openbsd-src/gnu/llvm/lldb/source/Plugins/ScriptInterpreter/Python/PythonDataObjects.h (revision 061da546b983eb767bad15e67af1174fb0bcf31c)
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