Logo ROOT  
Reference Guide
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// Bindings
13// CPyCppyy.h must be go first, since it includes Python.h, which must be
14// included before any standard header
15#include "CPyCppyy.h"
16#include "TPython.h"
17#include "CPPInstance.h"
18#include "CPPOverload.h"
19#include "ProxyWrappers.h"
20#include "TPyClassGenerator.h"
21
22// ROOT
23#include "TROOT.h"
24#include "TClassRef.h"
25#include "TObject.h"
26
27// Standard
28#include <stdio.h>
29#include <Riostream.h>
30#include <string>
31
32/// \class TPython
33/// Accessing the Python interpreter from C++.
34///
35/// The TPython class allows for access to python objects from Cling. The current
36/// functionality is only basic: ROOT objects and builtin types can freely cross
37/// the boundary between the two interpreters, python objects can be instantiated
38/// and their methods can be called. All other cross-coding is based on strings
39/// that are run on the python interpreter.
40///
41/// Examples:
42///
43/// ~~~{.cpp}
44/// $ root -l
45/// // Execute a string of python code.
46/// root [0] TPython::Exec( "print(\'Hello World!\')" );
47/// Hello World!
48///
49/// // Create a TBrowser on the python side, and transfer it back and forth.
50/// // Note the required explicit (void*) cast!
51/// root [1] TBrowser* b = (void*)TPython::Eval( "ROOT.TBrowser()" );
52/// root [2] TPython::Bind( b, "b" );
53/// root [3] b == (void*) TPython::Eval( "b" )
54/// (int)1
55///
56/// // Builtin variables can cross-over by using implicit casts.
57/// root [4] int i = TPython::Eval( "1 + 1" );
58/// root [5] i
59/// (int)2
60/// ~~~
61///
62/// And with a python file `MyPyClass.py` like this:
63/// ~~~{.py}
64/// print 'creating class MyPyClass ... '
65///
66/// class MyPyClass:
67/// def __init__( self ):
68/// print 'in MyPyClass.__init__'
69///
70/// def gime( self, what ):
71/// return what
72/// ~~~
73/// one can load a python module, and use the class. Casts are
74/// necessary as the type information can not be otherwise derived.
75/// ~~~{.cpp}
76/// root [6] TPython::LoadMacro( "MyPyClass.py" );
77/// creating class MyPyClass ...
78/// root [7] MyPyClass m;
79/// in MyPyClass.__init__
80/// root [8] std::string s = (char*)m.gime( "aap" );
81/// root [9] s
82/// (class TString)"aap"
83/// ~~~
84/// It is possible to switch between interpreters by calling `TPython::Prompt()`
85/// on the Cling side, while returning with `^D` (EOF). State is preserved between
86/// successive switches.
87///
88/// The API part provides (direct) C++ access to the bindings functionality of
89/// PyROOT. It allows verifying that you deal with a PyROOT python object in the
90/// first place (CPPInstance_Check for CPPInstance and any derived types, as well
91/// as CPPInstance_CheckExact for CPPInstance's only); and it allows conversions
92/// of `void*` to an CPPInstance and vice versa.
93
94//- data ---------------------------------------------------------------------
96static PyObject *gMainDict = 0;
97
98// needed to properly resolve (dllimport) symbols on Windows
99namespace CPyCppyy {
101 namespace PyStrings {
106 }
107}
108
109//- static public members ----------------------------------------------------
110/// Initialization method: setup the python interpreter and load the
111/// ROOT module.
113{
114 static Bool_t isInitialized = kFALSE;
115 if (isInitialized)
116 return kTRUE;
117
118 if (!Py_IsInitialized()) {
119// this happens if Cling comes in first
120#if PY_VERSION_HEX < 0x03020000
121 PyEval_InitThreads();
122#endif
123
124// set the command line arguments on python's sys.argv
125#if PY_VERSION_HEX < 0x03000000
126 char *argv[] = {const_cast<char *>("root")};
127#else
128 wchar_t *argv[] = {const_cast<wchar_t *>(L"root")};
129#endif
130 int argc = sizeof(argv) / sizeof(argv[0]);
131#if PY_VERSION_HEX < 0x030b0000
132 Py_Initialize();
133#else
134 PyStatus status;
135 PyConfig config;
136
137 PyConfig_InitPythonConfig(&config);
138
139 status = PyConfig_SetArgv(&config, argc, argv);
140 if (PyStatus_Exception(status)) {
141 PyConfig_Clear(&config);
142 std::cerr << "Error when setting command line arguments." << std::endl;
143 return kFALSE;
144 }
145
146 status = Py_InitializeFromConfig(&config);
147 if (PyStatus_Exception(status)) {
148 PyConfig_Clear(&config);
149 std::cerr << "Error when initializing Python." << std::endl;
150 return kFALSE;
151 }
152 PyConfig_Clear(&config);
153#endif
154#if PY_VERSION_HEX >= 0x03020000
155#if PY_VERSION_HEX < 0x03090000
156 PyEval_InitThreads();
157#endif
158#endif
159
160 // try again to see if the interpreter is initialized
161 if (!Py_IsInitialized()) {
162 // give up ...
163 std::cerr << "Error: python has not been intialized; returning." << std::endl;
164 return kFALSE;
165 }
166
167#if PY_VERSION_HEX < 0x030b0000
168 PySys_SetArgv(argc, argv);
169#endif
170
171 // force loading of the ROOT module
172 const int ret = PyRun_SimpleString(const_cast<char *>("import ROOT"));
173 if( ret != 0 )
174 {
175 std::cerr << "Error: import ROOT failed, check your PYTHONPATH environmental variable." << std::endl;
176 return kFALSE;
177 }
178 }
179
180 if (!gMainDict) {
181 // retrieve the main dictionary
182 gMainDict = PyModule_GetDict(PyImport_AddModule(const_cast<char *>("__main__")));
183 Py_INCREF(gMainDict);
184 }
185
186 // python side class construction, managed by ROOT
187 gROOT->AddClassGenerator(new TPyClassGenerator);
188
189 // declare success ...
190 isInitialized = kTRUE;
191 return kTRUE;
192}
193
194////////////////////////////////////////////////////////////////////////////////
195/// Import the named python module and create Cling equivalents for its classes
196/// and methods.
197
198Bool_t TPython::Import(const char *mod_name)
199{
200 // setup
201 if (!Initialize())
202 return kFALSE;
203
204 PyObject *mod = PyImport_ImportModule(mod_name);
205 if (!mod) {
206 PyErr_Print();
207 return kFALSE;
208 }
209
210 // allow finding to prevent creation of a python proxy for the C++ proxy
211 Py_INCREF(mod);
212 PyModule_AddObject(CPyCppyy::gThisModule, mod_name, mod);
213
214 // force creation of the module as a namespace
215 TClass::GetClass(mod_name, kTRUE);
216
217 PyObject *dct = PyModule_GetDict(mod);
218
219 // create Cling classes for all new python classes
220 PyObject *values = PyDict_Values(dct);
221 for (int i = 0; i < PyList_GET_SIZE(values); ++i) {
222 PyObject *value = PyList_GET_ITEM(values, i);
223 Py_INCREF(value);
224
225 // collect classes
226 if (PyClass_Check(value) || PyObject_HasAttr(value, CPyCppyy::PyStrings::gBases)) {
227 // get full class name (including module)
228 PyObject *pyClName = PyObject_GetAttr(value, CPyCppyy::PyStrings::gCppName);
229 if (!pyClName) {
230 pyClName = PyObject_GetAttr(value, CPyCppyy::PyStrings::gName);
231 }
232
233 if (PyErr_Occurred())
234 PyErr_Clear();
235
236 // build full, qualified name
237 std::string fullname = mod_name;
238 fullname += ".";
239 fullname += CPyCppyy_PyText_AsString(pyClName);
240
241 // force class creation (this will eventually call TPyClassGenerator)
242 TClass::GetClass(fullname.c_str(), kTRUE);
243
244 Py_XDECREF(pyClName);
245 }
246
247 Py_DECREF(value);
248 }
249
250 Py_DECREF(values);
251
252 // TODO: mod "leaks" here
253 if (PyErr_Occurred())
254 return kFALSE;
255 return kTRUE;
256}
257
258////////////////////////////////////////////////////////////////////////////////
259/// Execute the give python script as if it were a macro (effectively an
260/// execfile in __main__), and create Cling equivalents for any newly available
261/// python classes.
262
263void TPython::LoadMacro(const char *name)
264{
265 // setup
266 if (!Initialize())
267 return;
268
269 // obtain a reference to look for new classes later
270 PyObject *old = PyDict_Values(gMainDict);
271
272// actual execution
273#if PY_VERSION_HEX < 0x03000000
274 Exec((std::string("execfile(\"") + name + "\")").c_str());
275#else
276 Exec((std::string("__pyroot_f = open(\"") + name + "\"); "
277 "exec(__pyroot_f.read()); "
278 "__pyroot_f.close(); del __pyroot_f")
279 .c_str());
280#endif
281
282 // obtain new __main__ contents
283 PyObject *current = PyDict_Values(gMainDict);
284
285 // create Cling classes for all new python classes
286 for (int i = 0; i < PyList_GET_SIZE(current); ++i) {
287 PyObject *value = PyList_GET_ITEM(current, i);
288 Py_INCREF(value);
289
290 if (!PySequence_Contains(old, value)) {
291 // collect classes
292 if (PyClass_Check(value) || PyObject_HasAttr(value, CPyCppyy::PyStrings::gBases)) {
293 // get full class name (including module)
294 PyObject *pyModName = PyObject_GetAttr(value, CPyCppyy::PyStrings::gModule);
295 PyObject *pyClName = PyObject_GetAttr(value, CPyCppyy::PyStrings::gName);
296
297 if (PyErr_Occurred())
298 PyErr_Clear();
299
300 // need to check for both exact and derived (differences exist between older and newer
301 // versions of python ... bug?)
302 if ((pyModName && pyClName) &&
303 ((CPyCppyy_PyText_CheckExact(pyModName) && CPyCppyy_PyText_CheckExact(pyClName)) ||
304 (CPyCppyy_PyText_Check(pyModName) && CPyCppyy_PyText_Check(pyClName)))) {
305 // build full, qualified name
306 std::string fullname = CPyCppyy_PyText_AsString(pyModName);
307 fullname += '.';
308 fullname += CPyCppyy_PyText_AsString(pyClName);
309
310 // force class creation (this will eventually call TPyClassGenerator)
311 TClass::GetClass(fullname.c_str(), kTRUE);
312 }
313
314 Py_XDECREF(pyClName);
315 Py_XDECREF(pyModName);
316 }
317 }
318
319 Py_DECREF(value);
320 }
321
322 Py_DECREF(current);
323 Py_DECREF(old);
324}
325
326////////////////////////////////////////////////////////////////////////////////
327/// Execute a python stand-alone script, with argv CLI arguments.
328///
329/// example of use:
330/// const char* argv[] = { "1", "2", "3" };
331/// TPython::ExecScript( "test.py", sizeof(argv)/sizeof(argv[0]), argv );
332
333void TPython::ExecScript(const char *name, int argc, const char **argv)
334{
335
336 // setup
337 if (!Initialize())
338 return;
339
340 // verify arguments
341 if (!name) {
342 std::cerr << "Error: no file name specified." << std::endl;
343 return;
344 }
345
346 FILE *fp = fopen(name, "r");
347 if (!fp) {
348 std::cerr << "Error: could not open file \"" << name << "\"." << std::endl;
349 return;
350 }
351
352 // store a copy of the old cli for restoration
353 PyObject *oldargv = PySys_GetObject(const_cast<char *>("argv")); // borrowed
354 if (!oldargv) // e.g. apache
355 PyErr_Clear();
356 else {
357 PyObject *l = PyList_New(PyList_GET_SIZE(oldargv));
358 for (int i = 0; i < PyList_GET_SIZE(oldargv); ++i) {
359 PyObject *item = PyList_GET_ITEM(oldargv, i);
360 Py_INCREF(item);
361 PyList_SET_ITEM(l, i, item); // steals ref
362 }
363 oldargv = l;
364 }
365
366 // create and set (add progam name) the new command line
367 argc += 1;
368#if PY_VERSION_HEX < 0x03000000
369 const char **argv2 = new const char *[argc];
370 for (int i = 1; i < argc; ++i)
371 argv2[i] = argv[i - 1];
372 argv2[0] = Py_GetProgramName();
373 PySys_SetArgv(argc, const_cast<char **>(argv2));
374 delete[] argv2;
375#else
376// TODO: fix this to work like above ...
377 (void)argc;
378 (void)argv;
379#endif
380
381 // actual script execution
382 PyObject *gbl = PyDict_Copy(gMainDict);
383 PyObject *result = // PyRun_FileEx closes fp (b/c of last argument "1")
384 PyRun_FileEx(fp, const_cast<char *>(name), Py_file_input, gbl, gbl, 1);
385 if (!result)
386 PyErr_Print();
387 Py_XDECREF(result);
388 Py_DECREF(gbl);
389
390 // restore original command line
391 if (oldargv) {
392 PySys_SetObject(const_cast<char *>("argv"), oldargv);
393 Py_DECREF(oldargv);
394 }
395}
396
397////////////////////////////////////////////////////////////////////////////////
398/// Execute a python statement (e.g. "import ROOT").
399
400Bool_t TPython::Exec(const char *cmd)
401{
402 // setup
403 if (!Initialize())
404 return kFALSE;
405
406 // execute the command
407 PyObject *result = PyRun_String(const_cast<char *>(cmd), Py_file_input, gMainDict, gMainDict);
408
409 // test for error
410 if (result) {
411 Py_DECREF(result);
412 return kTRUE;
413 }
414
415 PyErr_Print();
416 return kFALSE;
417}
418
419////////////////////////////////////////////////////////////////////////////////
420/// Evaluate a python expression (e.g. "ROOT.TBrowser()").
421///
422/// Caution: do not hold on to the return value: either store it in a builtin
423/// type (implicit casting will work), or in a pointer to a ROOT object (explicit
424/// casting to a void* is required).
425
426const TPyReturn TPython::Eval(const char *expr)
427{
428 // setup
429 if (!Initialize())
430 return TPyReturn();
431
432 // evaluate the expression
433 PyObject *result = PyRun_String(const_cast<char *>(expr), Py_eval_input, gMainDict, gMainDict);
434
435 // report errors as appropriate; return void
436 if (!result) {
437 PyErr_Print();
438 return TPyReturn();
439 }
440
441 // results that require no conversion
442 if (result == Py_None || CPyCppyy::CPPInstance_Check(result) || PyBytes_Check(result) || PyFloat_Check(result) ||
443 PyLong_Check(result) || PyInt_Check(result))
444 return TPyReturn(result);
445
446 // explicit conversion for python type required
447 PyObject *pyclass = PyObject_GetAttrString(result, const_cast<char*>("__class__"));
448 if (pyclass != 0) {
449 // retrieve class name and the module in which it resides
450 PyObject *name = PyObject_GetAttr(pyclass, CPyCppyy::PyStrings::gName);
451 PyObject *module = PyObject_GetAttr(pyclass, CPyCppyy::PyStrings::gModule);
452
453 // concat name
454 std::string qname = std::string(CPyCppyy_PyText_AsString(module)) + '.' + CPyCppyy_PyText_AsString(name);
455 Py_DECREF(module);
456 Py_DECREF(name);
457 Py_DECREF(pyclass);
458
459 // locate ROOT style class with this name
460 TClass *klass = TClass::GetClass(qname.c_str());
461
462 // construct general ROOT python object that pretends to be of class 'klass'
463 if (klass != 0)
464 return TPyReturn(result);
465 } else
466 PyErr_Clear();
467
468 // no conversion, return null pointer object
469 Py_DECREF(result);
470 return TPyReturn();
471}
472
473////////////////////////////////////////////////////////////////////////////////
474/// Bind a ROOT object with, at the python side, the name "label".
475
476Bool_t TPython::Bind(TObject *object, const char *label)
477{
478 // check given address and setup
479 if (!(object && Initialize()))
480 return kFALSE;
481
482 // bind object in the main namespace
483 TClass *klass = object->IsA();
484 if (klass != 0) {
485 PyObject *bound = CPyCppyy::BindCppObject((void *)object, Cppyy::GetScope(klass->GetName()));
486
487 if (bound) {
488 Bool_t bOk = PyDict_SetItemString(gMainDict, const_cast<char *>(label), bound) == 0;
489 Py_DECREF(bound);
490
491 return bOk;
492 }
493 }
494
495 return kFALSE;
496}
497
498////////////////////////////////////////////////////////////////////////////////
499/// Enter an interactive python session (exit with ^D). State is preserved
500/// between successive calls.
501
503{
504 // setup
505 if (!Initialize()) {
506 return;
507 }
508
509 // enter i/o interactive mode
510 PyRun_InteractiveLoop(stdin, const_cast<char *>("\0"));
511}
512
513////////////////////////////////////////////////////////////////////////////////
514/// Test whether the type of the given pyobject is of CPPInstance type or any
515/// derived type.
516
518{
519 // setup
520 if (!Initialize())
521 return kFALSE;
522
523 // detailed walk through inheritance hierarchy
524 return CPyCppyy::CPPInstance_Check(pyobject);
525}
526
527////////////////////////////////////////////////////////////////////////////////
528/// Test whether the type of the given pyobject is CPPinstance type.
529
531{
532 // setup
533 if (!Initialize())
534 return kFALSE;
535
536 // direct pointer comparison of type member
537 return CPyCppyy::CPPInstance_CheckExact(pyobject);
538}
539
540////////////////////////////////////////////////////////////////////////////////
541/// Test whether the type of the given pyobject is of CPPOverload type or any
542/// derived type.
543
545{
546 // setup
547 if (!Initialize())
548 return kFALSE;
549
550 // detailed walk through inheritance hierarchy
551 return CPyCppyy::CPPOverload_Check(pyobject);
552}
553
554////////////////////////////////////////////////////////////////////////////////
555/// Test whether the type of the given pyobject is CPPOverload type.
556
558{
559 // setup
560 if (!Initialize())
561 return kFALSE;
562
563 // direct pointer comparison of type member
564 return CPyCppyy::CPPOverload_CheckExact(pyobject);
565}
566
567////////////////////////////////////////////////////////////////////////////////
568/// Extract the object pointer held by the CPPInstance pyobject.
569
571{
572 // setup
573 if (!Initialize())
574 return 0;
575
576 // check validity of cast
577 if (!CPyCppyy::CPPInstance_Check(pyobject))
578 return 0;
579
580 // get held object (may be null)
581 return ((CPyCppyy::CPPInstance *)pyobject)->GetObject();
582}
583
584////////////////////////////////////////////////////////////////////////////////
585/// Bind the addr to a python object of class defined by classname.
586
587PyObject *TPython::CPPInstance_FromVoidPtr(void *addr, const char *classname, Bool_t python_owns)
588{
589 // setup
590 if (!Initialize())
591 return 0;
592
593 // perform cast (the call will check TClass and addr, and set python errors)
594 PyObject *pyobject = CPyCppyy::BindCppObjectNoCast(addr, Cppyy::GetScope(classname), false);
595
596 // give ownership, for ref-counting, to the python side, if so requested
597 if (python_owns && CPyCppyy::CPPInstance_Check(pyobject))
598 ((CPyCppyy::CPPInstance *)pyobject)->PythonOwns();
599
600 return pyobject;
601}
#define PyBytes_Check
Definition: CPyCppyy.h:83
#define CPyCppyy_PyText_AsString
Definition: CPyCppyy.h:97
#define CPyCppyy_PyText_CheckExact
Definition: CPyCppyy.h:96
#define CPyCppyy_PyText_Check
Definition: CPyCppyy.h:95
#define R__EXTERN
Definition: DllImport.h:27
_object PyObject
Definition: PyMethodBase.h:43
const Bool_t kFALSE
Definition: RtypesCore.h:101
const Bool_t kTRUE
Definition: RtypesCore.h:100
#define ClassImp(name)
Definition: Rtypes.h:375
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:110
static PyObject * gMainDict
Definition: TPython.cxx:96
#define gROOT
Definition: TROOT.h:404
TClass instances represent classes, structs and namespaces in the ROOT type system.
Definition: TClass.h:80
TClass * IsA() const override
Definition: TClass.h:613
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:2968
const char * GetName() const override
Returns name of object.
Definition: TNamed.h:47
Mother of all ROOT objects.
Definition: TObject.h:37
Accessing the Python interpreter from C++.
Definition: TPython.h:29
static void Prompt()
Enter an interactive python session (exit with ^D).
Definition: TPython.cxx:502
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:544
static void * CPPInstance_AsVoidPtr(PyObject *pyobject)
Extract the object pointer held by the CPPInstance pyobject.
Definition: TPython.cxx:570
static Bool_t Import(const char *name)
Import the named python module and create Cling equivalents for its classes and methods.
Definition: TPython.cxx:198
static Bool_t CPPInstance_CheckExact(PyObject *pyobject)
Test whether the type of the given pyobject is CPPinstance type.
Definition: TPython.cxx:530
static Bool_t Bind(TObject *object, const char *label)
Bind a ROOT object with, at the python side, the name "label".
Definition: TPython.cxx:476
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:263
static Bool_t CPPOverload_CheckExact(PyObject *pyobject)
Test whether the type of the given pyobject is CPPOverload type.
Definition: TPython.cxx:557
static Bool_t Initialize()
Initialization method: setup the python interpreter and load the ROOT module.
Definition: TPython.cxx:112
static Bool_t Exec(const char *cmd)
Execute a python statement (e.g. "import ROOT").
Definition: TPython.cxx:400
static void ExecScript(const char *name, int argc=0, const char **argv=0)
Execute a python stand-alone script, with argv CLI arguments.
Definition: TPython.cxx:333
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:517
static const TPyReturn Eval(const char *expr)
Evaluate a python expression (e.g.
Definition: TPython.cxx:426
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:587
R__EXTERN PyObject * gName
Definition: TPython.cxx:105
R__EXTERN PyObject * gCppName
Definition: TPython.cxx:103
R__EXTERN PyObject * gBases
R__EXTERN PyObject * gModule
Definition: TPython.cxx:104
Set of helper functions that are invoked from the pythonizors, on the Python side.
PyObject * BindCppObjectNoCast(Cppyy::TCppObject_t object, Cppyy::TCppType_t klass, const unsigned flags=0)
bool CPPOverload_Check(T *object)
Definition: CPPOverload.h:79
bool CPPInstance_Check(T *object)
Definition: CPPInstance.h:118
bool CPPInstance_CheckExact(T *object)
Definition: CPPInstance.h:128
R__EXTERN PyObject * gThisModule
Definition: TPython.cxx:100
PyObject * BindCppObject(Cppyy::TCppObject_t object, Cppyy::TCppType_t klass, const unsigned flags=0)
bool CPPOverload_CheckExact(T *object)
Definition: CPPOverload.h:85
RPY_EXPORTED TCppScope_t GetScope(const std::string &scope_name)
void(off) SmallVectorTemplateBase< T
static constexpr double L
auto * l
Definition: textangle.C:4