Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
TPython.cxx
Go to the documentation of this file.
1// Author: Enric Tejedor CERN 08/2019
2// Original PyROOT code by Wim Lavrijsen, LBL
3//
4// /*************************************************************************
5// * Copyright (C) 1995-2019, Rene Brun and Fons Rademakers. *
6// * All rights reserved. *
7// * *
8// * For the licensing terms see $ROOTSYS/LICENSE. *
9// * For the list of contributors see $ROOTSYS/README/CREDITS. *
10// *************************************************************************/
11
12#include <Python.h>
13
14// Bindings
15// cpyrt.h must be go first, since it includes Python.h, which must be
16// included before any standard header
17#include "cpyrt/API.h"
18#include "TPython.h"
19#include "TPyClassGenerator.h"
20
21// ROOT
22#include "TROOT.h"
23#include "TClassRef.h"
24#include "TObject.h"
25
26// Standard
27#include <mutex>
28#include <sstream>
29#include <cstdio>
30#include <iostream>
31#include <string>
32
33/// \class TPython
34/// Accessing the Python interpreter from C++.
35///
36/// The TPython class allows for access to python objects from Cling. The current
37/// functionality is only basic: ROOT objects and builtin types can freely cross
38/// the boundary between the two interpreters, python objects can be instantiated
39/// and their methods can be called. All other cross-coding is based on strings
40/// that are run on the python interpreter.
41///
42/// Examples:
43///
44/// ~~~{.cpp}
45/// $ root -l
46/// // Execute a string of python code.
47/// root [0] TPython::Exec( "print('Hello World!')" );
48/// Hello World!
49///
50/// // Create a TNamed on the python side, and transfer it back and forth.
51/// root [1] std::any res1;
52/// root [2] TPython::Exec("_anyresult = ROOT.std.make_any['TNamed']('hello', '')", &res1);
53/// root [3] TPython::Bind(&std::any_cast<TNamed&>(res1), "n");
54/// root [4] std::any res2;
55/// root [5] TPython::Exec("_anyresult = ROOT.std.make_any['TNamed*', 'TNamed*'](n)", &res2);
56/// root [6] (&std::any_cast<TNamed&>(res1) == std::any_cast<TNamed*>(res2))
57/// (bool) true
58///
59/// // Variables can cross-over by using an `std::any` with a specific name.
60/// root [6] TPython::Exec("_anyresult = ROOT.std.make_any['Int_t'](1 + 1)", &res1);
61/// root [7] std::any_cast<int>(res1)
62/// (int) 2
63/// ~~~
64///
65/// And with a python file `MyPyClass.py` like this:
66/// ~~~{.py}
67/// print 'creating class MyPyClass ... '
68///
69/// class MyPyClass:
70/// def __init__( self ):
71/// print 'in MyPyClass.__init__'
72///
73/// def gime( self, what ):
74/// return what
75/// ~~~
76/// one can load a python module, and use the class. Casts are
77/// necessary as the type information can not be otherwise derived.
78/// ~~~{.cpp}
79/// root [6] TPython::LoadMacro( "MyPyClass.py" );
80/// creating class MyPyClass ...
81/// root [7] MyPyClass m;
82/// in MyPyClass.__init__
83/// root [8] std::string s = (char*)m.gime( "aap" );
84/// root [9] s
85/// (class TString)"aap"
86/// ~~~
87/// It is possible to switch between interpreters by calling `TPython::Prompt()`
88/// on the Cling side, while returning with `^D` (EOF). State is preserved between
89/// successive switches.
90///
91/// The API part provides (direct) C++ access to the bindings functionality of
92/// PyROOT. It allows verifying that you deal with a PyROOT python object in the
93/// first place (CPPInstance_Check for CPPInstance and any derived types, as well
94/// as CPPInstance_CheckExact for CPPInstance's only); and it allows conversions
95/// of `void*` to an CPPInstance and vice versa.
96
97//- data ---------------------------------------------------------------------
98static PyObject *gMainDict = 0;
99
100namespace {
101
102PyThreadState *mainThreadState;
103
104// To acquire the GIL as described here:
105// https://docs.python.org/3/c-api/init.html#non-python-created-threads
106class PyGILRAII {
107 PyGILState_STATE m_GILState;
108
109public:
110 PyGILRAII() : m_GILState(PyGILState_Ensure()) {}
111 ~PyGILRAII() { PyGILState_Release(m_GILState); }
112};
113
114struct PyObjDeleter {
115 void operator()(PyObject* obj) const {
116 Py_DecRef(obj);
117 }
118};
119
120using PyObjectRef = std::unique_ptr<PyObject, PyObjDeleter>;
121
122} // namespace
123
124//- static public members ----------------------------------------------------
125/// Initialization method: setup the python interpreter and load the
126/// ROOT module.
128{
129 // Don't initialize Python from two concurrent threads
130 static std::mutex initMutex;
131 const std::lock_guard<std::mutex> lock(initMutex);
132
133 static Bool_t isInitialized = false;
134 static Bool_t pythonInitializationFailed = false;
135 if (isInitialized)
136 return true;
137
138 if (!Py_IsInitialized()) {
139 // Retrying after failed initialization can abort in CPython.
140 if (pythonInitializationFailed)
141 return false;
142
143 // Trigger the Python initialization indirectly via cpyrt
145 if (!Py_IsInitialized()) {
146 pythonInitializationFailed = true;
147 return false;
148 }
149
150 mainThreadState = PyEval_SaveThread();
151 }
152
153 {
154 // For the Python API calls
155 PyGILRAII gilRaii;
156
157 // force loading of the ROOT module
158 PyObject* rootModule = PyImport_ImportModule("ROOT");
159 if (!rootModule) {
160 PyErr_Print();
161 return false;
162 }
163
164 // to trigger the lazy initialization of the C++ runtime
165 PyObject* interpreterAttr = PyObject_GetAttrString(rootModule, "gInterpreter");
166 if (!interpreterAttr) {
167 PyErr_Print();
168 Py_DecRef(rootModule);
169 return false;
170 }
171
172 Py_DecRef(interpreterAttr);
173
174 if (!gMainDict) {
175
176 // retrieve the main dictionary
177 gMainDict = PyModule_GetDict(PyImport_AddModule("__main__"));
178 // The gMainDict is borrowed, i.e. we are not calling Py_IncRef(gMainDict).
179 // Like this, we avoid unexpectedly affecting how long __main__ is kept
180 // alive. The gMainDict is only used in Exec(), ExecScript(), and Eval(),
181 // which should not be called after __main__ is garbage collected anyway.
182 }
183
184 // Inject ROOT into __main__
185 if (PyDict_SetItemString(gMainDict, "ROOT", rootModule) != 0) {
186 PyErr_Print();
187 Py_DecRef(rootModule);
188 return false;
189 }
190
191 Py_DecRef(rootModule);
192 }
193
194 // python side class construction, managed by ROOT
195 gROOT->AddClassGenerator(new TPyClassGenerator);
196
197 // declare success ...
198 isInitialized = true;
199 return true;
200}
201
202////////////////////////////////////////////////////////////////////////////////
203/// Import the named python module and create Cling equivalents for its classes
204/// and methods.
205
206Bool_t TPython::Import(const char *mod_name)
207{
208 // setup
209 if (!Initialize())
210 return false;
211
212 PyGILRAII gilRaii;
213
214 if (!cppjit::cpyrt::Import(mod_name)) {
215 return false;
216 }
217
218 // force creation of the module as a namespace
219 TClass::GetClass(mod_name, true);
220
221 PyObjectRef modNameObj{PyUnicode_FromString(mod_name)};
222 PyObjectRef mod{PyImport_GetModule(modNameObj.get())};
223 PyObject *dct = PyModule_GetDict(mod.get());
224
225 PyObjectRef basesStr{PyUnicode_FromString("__bases__")};
226 PyObjectRef cppNameStr{PyUnicode_FromString("__cpp_name__")};
227 PyObjectRef nameStr{PyUnicode_FromString("__name__")};
228
229 // create Cling classes for all new python classes
230 PyObjectRef values{PyDict_Values(dct)};
231 for (int i = 0; i < PyList_Size(values.get()); ++i) {
232 PyObjectRef value{PyList_GetItem(values.get(), i)};
233 Py_IncRef(value.get());
234
235 // collect classes
236 if (PyType_Check(value.get()) || PyObject_HasAttr(value.get(), basesStr.get())) {
237 // get full class name (including module)
238 PyObjectRef pyClName{PyObject_GetAttr(value.get(), cppNameStr.get())};
239 if (!pyClName) {
240 if (PyErr_Occurred())
241 PyErr_Clear();
242 pyClName = PyObjectRef{PyObject_GetAttr(value.get(), nameStr.get())};
243 }
244
245 if (PyErr_Occurred())
246 PyErr_Clear();
247
248 // build full, qualified name
249 std::string fullname = mod_name;
250 fullname += ".";
251 fullname += PyUnicode_AsUTF8AndSize(pyClName.get(), nullptr);
252
253 // force class creation (this will eventually call TPyClassGenerator)
254 TClass::GetClass(fullname.c_str(), true);
255 }
256 }
257
258 return !PyErr_Occurred();
259}
260
261////////////////////////////////////////////////////////////////////////////////
262/// Execute the give python script as if it were a macro (effectively an
263/// execfile in __main__), and create Cling equivalents for any newly available
264/// python classes.
265
266void TPython::LoadMacro(const char *name)
267{
268 // setup
269 if (!Initialize())
270 return;
271
272 PyGILRAII gilRaii;
273
274 // obtain a reference to look for new classes later
275 PyObjectRef old{PyDict_Values(gMainDict)};
276
277 // escape characters in the file name that would otherwise terminate or
278 // alter the Python string literal we put the file name into below
279 std::string escapedName;
280 escapedName.reserve(std::char_traits<char>::length(name));
281 for (const char *p = name; *p; ++p) {
282 switch (*p) {
283 case '\\': escapedName += "\\\\"; break;
284 case '"': escapedName += "\\\""; break;
285 case '\n': escapedName += "\\n"; break;
286 case '\r': escapedName += "\\r"; break;
287 default: escapedName += *p; break;
288 }
289 }
290
291 // actual execution
292 Exec((std::string("__pyroot_f = open(\"") + escapedName +
293 "\"); "
294 "exec(__pyroot_f.read()); "
295 "__pyroot_f.close(); del __pyroot_f")
296 .c_str());
297
298 // obtain new __main__ contents
299 PyObjectRef current{PyDict_Values(gMainDict)};
300
301 PyObjectRef basesStr{PyUnicode_FromString("__bases__")};
302 PyObjectRef moduleStr{PyUnicode_FromString("__module__")};
303 PyObjectRef nameStr{PyUnicode_FromString("__name__")};
304
305 // create Cling classes for all new python classes
306 for (int i = 0; i < PyList_Size(current.get()); ++i) {
307 PyObjectRef value{PyList_GetItem(current.get(), i)};
308 Py_IncRef(value.get());
309
310 if (!PySequence_Contains(old.get(), value.get())) {
311 // collect classes
312 if (PyType_Check(value.get()) || PyObject_HasAttr(value.get(), basesStr.get())) {
313 // get full class name (including module)
314 PyObjectRef pyModName{PyObject_GetAttr(value.get(), moduleStr.get())};
315 PyObjectRef pyClName{PyObject_GetAttr(value.get(), nameStr.get())};
316
317 if (PyErr_Occurred())
318 PyErr_Clear();
319
320 // need to check for both exact and derived (differences exist between older and newer
321 // versions of python ... bug?)
322 if ((pyModName && pyClName) && ((PyUnicode_CheckExact(pyModName.get()) && PyUnicode_CheckExact(pyClName.get())) ||
323 (PyUnicode_Check(pyModName.get()) && PyUnicode_Check(pyClName.get())))) {
324 // build full, qualified name
325 std::string fullname = PyUnicode_AsUTF8AndSize(pyModName.get(), nullptr);
326 fullname += '.';
327 fullname += PyUnicode_AsUTF8AndSize(pyClName.get(), nullptr);
328
329 // force class creation (this will eventually call TPyClassGenerator)
330 TClass::GetClass(fullname.c_str(), true);
331 }
332 }
333 }
334 }
335}
336
337////////////////////////////////////////////////////////////////////////////////
338/// Execute a python stand-alone script, with argv CLI arguments.
339///
340/// example of use:
341/// const char* argv[] = { "1", "2", "3" };
342/// TPython::ExecScript( "test.py", sizeof(argv)/sizeof(argv[0]), argv );
343
344void TPython::ExecScript(const char *name, int argc, const char **argv)
345{
346
347 // setup
348 if (!Initialize())
349 return;
350
351 PyGILRAII gilRaii;
352
353 // verify arguments
354 if (!name) {
355 std::cerr << "Error: no file name specified." << std::endl;
356 return;
357 }
358
359 std::vector<std::string> args(argc);
360 for (int i = 0; i < argc; ++i) {
361 args[i] = argv[i];
362 }
364}
365
366////////////////////////////////////////////////////////////////////////////////
367/// Executes a Python command within the current Python environment.
368///
369/// This function initializes the Python environment if it is not already
370/// initialized. It then executes the specified Python command string using the
371/// Python C API.
372///
373/// In the Python command, you can change the value of a special TPyResult
374/// object returned by TPyBuffer(). If the optional result parameter is
375/// non-zero, the result parameter will be swapped with a std::any variable on
376/// the Python side. You need to define this variable yourself, and it needs to
377/// be of type std::any and its name needs to be `"_anyresult"` by default.
378/// Like this, you can pass information from Python back to C++.
379///
380/// \param cmd The Python command to be executed as a string.
381/// \param result Optional pointer to a std::any object that can be used to
382/// transfer results from Python to C++.
383/// \param resultName Name of the Python variable that is swapped over to the std::any result.
384/// The default value is `"_anyresult"`.
385/// \return bool Returns `true` if the command was successfully executed,
386/// otherwise returns `false`.
387
388Bool_t TPython::Exec(const char *cmd, std::any *result, std::string const &resultName)
389{
390 // setup
391 if (!Initialize())
392 return false;
393
394 PyGILRAII gilRaii;
395
396 std::stringstream command;
397 // Add the actual command
398 command << cmd;
399 // Swap the std::any with the one in the C++ world if required
400 if (result) {
401 command << "; ROOT.Internal.SwapWithObjAtAddr['std::any'](" << resultName << ", "
402 << reinterpret_cast<std::intptr_t>(result) << ")";
403 }
404
405 // execute the command
406 return cppjit::cpyrt::Exec(command.str());
407}
408
409////////////////////////////////////////////////////////////////////////////////
410/// Bind a ROOT object with, at the python side, the name "label".
411
412Bool_t TPython::Bind(TObject *object, const char *label)
413{
414 // check given address and setup
415 if (!(object && Initialize()))
416 return false;
417
418 PyGILRAII gilRaii;
419
420 // bind object in the main namespace
421 TClass *klass = object->IsA();
422 if (klass != 0) {
423 PyObjectRef bound{cppjit::cpyrt::Instance_FromVoidPtr((void *)object, klass->GetName())};
424
425 if (bound) {
426 Bool_t bOk = PyDict_SetItemString(gMainDict, label, bound.get()) == 0;
427
428 return bOk;
429 }
430 }
431
432 return false;
433}
434
435////////////////////////////////////////////////////////////////////////////////
436/// Enter an interactive python session (exit with ^D). State is preserved
437/// between successive calls.
438
440{
441 // setup
442 if (!Initialize()) {
443 return;
444 }
445
446 PyGILRAII gilRaii;
447
448 // enter i/o interactive mode
450}
451
452////////////////////////////////////////////////////////////////////////////////
453/// Test whether the type of the given pyobject is of CPPInstance type or any
454/// derived type.
455
457{
458 // setup
459 if (!Initialize())
460 return false;
461
462 PyGILRAII gilRaii;
463
464 // detailed walk through inheritance hierarchy
465 return cppjit::cpyrt::Instance_Check(pyobject);
466}
467
468////////////////////////////////////////////////////////////////////////////////
469/// Test whether the type of the given pyobject is CPPinstance type.
470
472{
473 // setup
474 if (!Initialize())
475 return false;
476
477 PyGILRAII gilRaii;
478
479 // direct pointer comparison of type member
480 return cppjit::cpyrt::Instance_CheckExact(pyobject);
481}
482
483////////////////////////////////////////////////////////////////////////////////
484/// Test whether the type of the given pyobject is of CPPOverload type or any
485/// derived type.
486
488{
489 // setup
490 if (!Initialize())
491 return false;
492
493 PyGILRAII gilRaii;
494
495 // detailed walk through inheritance hierarchy
496 return cppjit::cpyrt::Overload_Check(pyobject);
497}
498
499////////////////////////////////////////////////////////////////////////////////
500/// Test whether the type of the given pyobject is CPPOverload type.
501
503{
504 // setup
505 if (!Initialize())
506 return false;
507
508 PyGILRAII gilRaii;
509
510 // direct pointer comparison of type member
511 return cppjit::cpyrt::Overload_CheckExact(pyobject);
512}
513
514////////////////////////////////////////////////////////////////////////////////
515/// Extract the object pointer held by the CPPInstance pyobject.
516
518{
519 // setup
520 if (!Initialize())
521 return nullptr;
522
523 PyGILRAII gilRaii;
524
525 // get held object (may be null)
526 return cppjit::cpyrt::Instance_AsVoidPtr(pyobject);
527}
528
529////////////////////////////////////////////////////////////////////////////////
530/// Bind the addr to a python object of class defined by classname.
531
532PyObject *TPython::CPPInstance_FromVoidPtr(void *addr, const char *classname, Bool_t python_owns)
533{
534 // setup
535 if (!Initialize())
536 return nullptr;
537
538 PyGILRAII gilRaii;
539
540 // perform cast (the call will check TClass and addr, and set python errors)
541 // give ownership, for ref-counting, to the python side, if so requested
542 return cppjit::cpyrt::Instance_FromVoidPtr(addr, classname, python_owns);
543}
_object PyObject
winID h TVirtualViewer3D TVirtualGLPainter p
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t result
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void value
char name[80]
Definition TGX11.cxx:142
static PyObject * gMainDict
Definition TPython.cxx:98
_object PyObject
Definition TPython.h:23
#define gROOT
Definition TROOT.h:417
TClass instances represent classes, structs and namespaces in the ROOT type system.
Definition TClass.h:84
TClass * IsA() const override
Definition TClass.h:638
static TClass * GetClass(const char *name, Bool_t load=kTRUE, Bool_t silent=kFALSE)
Static method returning pointer to TClass of the specified class name.
Definition TClass.cxx:2999
const char * GetName() const override
Returns name of object.
Definition TNamed.h:49
Mother of all ROOT objects.
Definition TObject.h:42
static void Prompt()
Enter an interactive python session (exit with ^D).
Definition TPython.cxx:439
static Bool_t CPPOverload_Check(PyObject *pyobject)
Test whether the type of the given pyobject is of CPPOverload type or any derived type.
Definition TPython.cxx:487
static void * CPPInstance_AsVoidPtr(PyObject *pyobject)
Extract the object pointer held by the CPPInstance pyobject.
Definition TPython.cxx:517
static void ExecScript(const char *name, int argc=0, const char **argv=nullptr)
Execute a python stand-alone script, with argv CLI arguments.
Definition TPython.cxx:344
static Bool_t Import(const char *name)
Import the named python module and create Cling equivalents for its classes and methods.
Definition TPython.cxx:206
static Bool_t CPPInstance_CheckExact(PyObject *pyobject)
Test whether the type of the given pyobject is CPPinstance type.
Definition TPython.cxx:471
static Bool_t Bind(TObject *object, const char *label)
Bind a ROOT object with, at the python side, the name "label".
Definition TPython.cxx:412
static void LoadMacro(const char *name)
Execute the give python script as if it were a macro (effectively an execfile in main),...
Definition TPython.cxx:266
static Bool_t Exec(const char *cmd, std::any *result=nullptr, std::string const &resultName="_anyresult")
Executes a Python command within the current Python environment.
Definition TPython.cxx:388
static Bool_t CPPOverload_CheckExact(PyObject *pyobject)
Test whether the type of the given pyobject is CPPOverload type.
Definition TPython.cxx:502
static Bool_t Initialize()
Initialization method: setup the python interpreter and load the ROOT module.
Definition TPython.cxx:127
static Bool_t CPPInstance_Check(PyObject *pyobject)
Test whether the type of the given pyobject is of CPPInstance type or any derived type.
Definition TPython.cxx:456
static PyObject * CPPInstance_FromVoidPtr(void *addr, const char *classname, Bool_t python_owns=kFALSE)
Bind the addr to a python object of class defined by classname.
Definition TPython.cxx:532
CPYRT_EXTERN bool Exec(const std::string &cmd)
Definition API.cxx:447
CPYRT_EXTERN bool Scope_Check(PyObject *pyobject)
Definition API.cxx:168
CPYRT_EXTERN bool Overload_Check(PyObject *pyobject)
Definition API.cxx:283
CPYRT_EXTERN bool Instance_Check(PyObject *pyobject)
Definition API.cxx:188
CPYRT_EXTERN void ExecScript(const std::string &name, const std::vector< std::string > &args)
Definition API.cxx:367
CPYRT_EXTERN void Prompt()
Definition API.cxx:468
CPYRT_EXTERN void * Instance_AsVoidPtr(PyObject *pyobject)
Definition API.cxx:105
CPYRT_EXTERN bool Overload_CheckExact(PyObject *pyobject)
Definition API.cxx:294
PyObject * Instance_FromVoidPtr(void *addr, const char *classname, int python_owns)
Definition API.cxx:161
CPYRT_EXTERN bool Instance_CheckExact(PyObject *pyobject)
Definition API.cxx:199
CPYRT_EXTERN bool Import(const std::string &name)
Definition API.cxx:310