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// 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/API.h"
16#include "TPython.h"
17#include "TPyClassGenerator.h"
18
19// ROOT
20#include "TROOT.h"
21#include "TClassRef.h"
22#include "TObject.h"
23
24#include <Riostream.h>
25
26// Standard
27#include <mutex>
28#include <sstream>
29#include <stdio.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 TNamed on the python side, and transfer it back and forth.
50/// root [1] std::any res1;
51/// root [2] TPython::Exec("_anyresult = ROOT.std.make_any['TNamed']('hello', '')", &res1);
52/// root [3] TPython::Bind(&std::any_cast<TNamed&>(res1), "n");
53/// root [4] std::any res2;
54/// root [5] TPython::Exec("_anyresult = ROOT.std.make_any['TNamed*', 'TNamed*'](n)", &res2);
55/// root [6] (&std::any_cast<TNamed&>(res1) == std::any_cast<TNamed*>(res2))
56/// (bool) true
57///
58/// // Variables can cross-over by using an `std::any` with a specific name.
59/// root [6] TPython::Exec("_anyresult = ROOT.std.make_any['Int_t'](1 + 1)", &res1);
60/// root [7] std::any_cast<int>(res1)
61/// (int) 2
62/// ~~~
63///
64/// And with a python file `MyPyClass.py` like this:
65/// ~~~{.py}
66/// print 'creating class MyPyClass ... '
67///
68/// class MyPyClass:
69/// def __init__( self ):
70/// print 'in MyPyClass.__init__'
71///
72/// def gime( self, what ):
73/// return what
74/// ~~~
75/// one can load a python module, and use the class. Casts are
76/// necessary as the type information can not be otherwise derived.
77/// ~~~{.cpp}
78/// root [6] TPython::LoadMacro( "MyPyClass.py" );
79/// creating class MyPyClass ...
80/// root [7] MyPyClass m;
81/// in MyPyClass.__init__
82/// root [8] std::string s = (char*)m.gime( "aap" );
83/// root [9] s
84/// (class TString)"aap"
85/// ~~~
86/// It is possible to switch between interpreters by calling `TPython::Prompt()`
87/// on the Cling side, while returning with `^D` (EOF). State is preserved between
88/// successive switches.
89///
90/// The API part provides (direct) C++ access to the bindings functionality of
91/// PyROOT. It allows verifying that you deal with a PyROOT python object in the
92/// first place (CPPInstance_Check for CPPInstance and any derived types, as well
93/// as CPPInstance_CheckExact for CPPInstance's only); and it allows conversions
94/// of `void*` to an CPPInstance and vice versa.
95
96//- data ---------------------------------------------------------------------
97static PyObject *gMainDict = 0;
98
99namespace {
100
102
103// To acquire the GIL as described here:
104// https://docs.python.org/3/c-api/init.html#non-python-created-threads
105class PyGILRAII {
106 PyGILState_STATE m_GILState;
107
108public:
109 PyGILRAII() : m_GILState(PyGILState_Ensure()) {}
110 ~PyGILRAII() { PyGILState_Release(m_GILState); }
111};
112
113struct PyObjDeleter {
114 void operator()(PyObject* obj) const {
115 Py_DecRef(obj);
116 }
117};
118
119using PyObjectRef = std::unique_ptr<PyObject, PyObjDeleter>;
120
121} // namespace
122
123//- static public members ----------------------------------------------------
124/// Initialization method: setup the python interpreter and load the
125/// ROOT module.
127{
128 // Don't initialize Python from two concurrent threads
129 static std::mutex initMutex;
130 const std::lock_guard<std::mutex> lock(initMutex);
131
132 static Bool_t isInitialized = false;
133 if (isInitialized)
134 return true;
135
136 if (!Py_IsInitialized()) {
137 wchar_t rootStr[] = L"root";
138 wchar_t *argv[] = {rootStr};
139 int argc = sizeof(argv) / sizeof(argv[0]);
140#if PY_VERSION_HEX < 0x030b0000
142#else
143 PyStatus status;
144 PyConfig config;
145
147
148 status = PyConfig_SetArgv(&config, argc, argv);
149 if (PyStatus_Exception(status)) {
150 PyConfig_Clear(&config);
151 std::cerr << "Error when setting command line arguments." << std::endl;
152 return false;
153 }
154
155 status = Py_InitializeFromConfig(&config);
156 if (PyStatus_Exception(status)) {
157 PyConfig_Clear(&config);
158 std::cerr << "Error when initializing Python." << std::endl;
159 return false;
160 }
161 PyConfig_Clear(&config);
162#endif
163#if PY_VERSION_HEX < 0x03090000
165#endif
166
167 // try again to see if the interpreter is initialized
168 if (!Py_IsInitialized()) {
169 // give up ...
170 std::cerr << "Error: python has not been intialized; returning." << std::endl;
171 return false;
172 }
173
174#if PY_VERSION_HEX < 0x030b0000
176#endif
177
179 }
180
181 {
182 // For the Python API calls
183 PyGILRAII gilRaii;
184
185 // force loading of the ROOT module
186 const int ret = PyRun_SimpleString("import ROOT");
187 if (ret != 0) {
188 std::cerr << "Error: import ROOT failed, check your PYTHONPATH environmental variable." << std::endl;
189 return false;
190 }
191
192 if (!gMainDict) {
193
194 // retrieve the main dictionary
196 // The gMainDict is borrowed, i.e. we are not calling Py_IncRef(gMainDict).
197 // Like this, we avoid unexpectedly affecting how long __main__ is kept
198 // alive. The gMainDict is only used in Exec(), ExecScript(), and Eval(),
199 // which should not be called after __main__ is garbage collected anyway.
200 }
201 }
202
203 // python side class construction, managed by ROOT
204 gROOT->AddClassGenerator(new TPyClassGenerator);
205
206 // declare success ...
207 isInitialized = true;
208 return true;
209}
210
211////////////////////////////////////////////////////////////////////////////////
212/// Import the named python module and create Cling equivalents for its classes
213/// and methods.
214
216{
217 // setup
218 if (!Initialize())
219 return false;
220
221 PyGILRAII gilRaii;
222
224 return false;
225 }
226
227 // force creation of the module as a namespace
229
233
237
238 // create Cling classes for all new python classes
240 for (int i = 0; i < PyList_Size(values.get()); ++i) {
241 PyObjectRef value{PyList_GetItem(values.get(), i)};
242 Py_IncRef(value.get());
243
244 // collect classes
245 if (PyType_Check(value.get()) || PyObject_HasAttr(value.get(), basesStr.get())) {
246 // get full class name (including module)
248 if (!pyClName) {
249 if (PyErr_Occurred())
250 PyErr_Clear();
252 }
253
254 if (PyErr_Occurred())
255 PyErr_Clear();
256
257 // build full, qualified name
258 std::string fullname = mod_name;
259 fullname += ".";
260 fullname += PyUnicode_AsUTF8AndSize(pyClName.get(), nullptr);
261
262 // force class creation (this will eventually call TPyClassGenerator)
263 TClass::GetClass(fullname.c_str(), true);
264 }
265 }
266
267 return !PyErr_Occurred();
268}
269
270////////////////////////////////////////////////////////////////////////////////
271/// Execute the give python script as if it were a macro (effectively an
272/// execfile in __main__), and create Cling equivalents for any newly available
273/// python classes.
274
275void TPython::LoadMacro(const char *name)
276{
277 // setup
278 if (!Initialize())
279 return;
280
281 PyGILRAII gilRaii;
282
283 // obtain a reference to look for new classes later
285
286// actual execution
287 Exec((std::string("__pyroot_f = open(\"") + name +
288 "\"); "
289 "exec(__pyroot_f.read()); "
290 "__pyroot_f.close(); del __pyroot_f")
291 .c_str());
292
293 // obtain new __main__ contents
295
299
300 // create Cling classes for all new python classes
301 for (int i = 0; i < PyList_Size(current.get()); ++i) {
302 PyObjectRef value{PyList_GetItem(current.get(), i)};
303 Py_IncRef(value.get());
304
305 if (!PySequence_Contains(old.get(), value.get())) {
306 // collect classes
307 if (PyType_Check(value.get()) || PyObject_HasAttr(value.get(), basesStr.get())) {
308 // get full class name (including module)
311
312 if (PyErr_Occurred())
313 PyErr_Clear();
314
315 // need to check for both exact and derived (differences exist between older and newer
316 // versions of python ... bug?)
319 // build full, qualified name
320 std::string fullname = PyUnicode_AsUTF8AndSize(pyModName.get(), nullptr);
321 fullname += '.';
322 fullname += PyUnicode_AsUTF8AndSize(pyClName.get(), nullptr);
323
324 // force class creation (this will eventually call TPyClassGenerator)
325 TClass::GetClass(fullname.c_str(), true);
326 }
327 }
328 }
329 }
330}
331
332////////////////////////////////////////////////////////////////////////////////
333/// Execute a python stand-alone script, with argv CLI arguments.
334///
335/// example of use:
336/// const char* argv[] = { "1", "2", "3" };
337/// TPython::ExecScript( "test.py", sizeof(argv)/sizeof(argv[0]), argv );
338
339void TPython::ExecScript(const char *name, int argc, const char **argv)
340{
341
342 // setup
343 if (!Initialize())
344 return;
345
346 PyGILRAII gilRaii;
347
348 // verify arguments
349 if (!name) {
350 std::cerr << "Error: no file name specified." << std::endl;
351 return;
352 }
353
354 std::vector<std::string> args(argc);
355 for (int i = 0; i < argc; ++i) {
356 args[i] = argv[i];
357 }
359}
360
361////////////////////////////////////////////////////////////////////////////////
362/// Executes a Python command within the current Python environment.
363///
364/// This function initializes the Python environment if it is not already
365/// initialized. It then executes the specified Python command string using the
366/// Python C API.
367///
368/// In the Python command, you can change the value of a special TPyResult
369/// object returned by TPyBuffer(). If the optional result parameter is
370/// non-zero, the result parameter will be swapped with a std::any variable on
371/// the Python side. You need to define this variable yourself, and it needs to
372/// be of type std::any and its name needs to be `"_anyresult"` by default.
373/// Like this, you can pass information from Python back to C++.
374///
375/// \param cmd The Python command to be executed as a string.
376/// \param result Optional pointer to a std::any object that can be used to
377/// transfer results from Python to C++.
378/// \param resultName Name of the Python variable that is swapped over to the std::any result.
379/// The default value is `"_anyresult"`.
380/// \return bool Returns `true` if the command was successfully executed,
381/// otherwise returns `false`.
382
383Bool_t TPython::Exec(const char *cmd, std::any *result, std::string const &resultName)
384{
385 // setup
386 if (!Initialize())
387 return false;
388
389 PyGILRAII gilRaii;
390
391 std::stringstream command;
392 // Add the actual command
393 command << cmd;
394 // Swap the std::any with the one in the C++ world if required
395 if (result) {
396 command << "; ROOT.Internal.SwapWithObjAtAddr['std::any'](" << resultName << ", "
397 << reinterpret_cast<std::intptr_t>(result) << ")";
398 }
399
400 // execute the command
403
404 // test for error
405 if (pyObjectResult) {
406 return true;
407 }
408
409 PyErr_Print();
410 return false;
411}
412
413////////////////////////////////////////////////////////////////////////////////
414/// Bind a ROOT object with, at the python side, the name "label".
415
416Bool_t TPython::Bind(TObject *object, const char *label)
417{
418 // check given address and setup
419 if (!(object && Initialize()))
420 return false;
421
422 PyGILRAII gilRaii;
423
424 // bind object in the main namespace
425 TClass *klass = object->IsA();
426 if (klass != 0) {
427 PyObjectRef bound{CPyCppyy::Instance_FromVoidPtr((void *)object, klass->GetName())};
428
429 if (bound) {
430 Bool_t bOk = PyDict_SetItemString(gMainDict, label, bound.get()) == 0;
431
432 return bOk;
433 }
434 }
435
436 return false;
437}
438
439////////////////////////////////////////////////////////////////////////////////
440/// Enter an interactive python session (exit with ^D). State is preserved
441/// between successive calls.
442
444{
445 // setup
446 if (!Initialize()) {
447 return;
448 }
449
450 PyGILRAII gilRaii;
451
452 // enter i/o interactive mode
454}
455
456////////////////////////////////////////////////////////////////////////////////
457/// Test whether the type of the given pyobject is of CPPInstance type or any
458/// derived type.
459
461{
462 // setup
463 if (!Initialize())
464 return false;
465
466 PyGILRAII gilRaii;
467
468 // detailed walk through inheritance hierarchy
470}
471
472////////////////////////////////////////////////////////////////////////////////
473/// Test whether the type of the given pyobject is CPPinstance type.
474
476{
477 // setup
478 if (!Initialize())
479 return false;
480
481 PyGILRAII gilRaii;
482
483 // direct pointer comparison of type member
485}
486
487////////////////////////////////////////////////////////////////////////////////
488/// Test whether the type of the given pyobject is of CPPOverload type or any
489/// derived type.
490
492{
493 // setup
494 if (!Initialize())
495 return false;
496
497 PyGILRAII gilRaii;
498
499 // detailed walk through inheritance hierarchy
501}
502
503////////////////////////////////////////////////////////////////////////////////
504/// Test whether the type of the given pyobject is CPPOverload type.
505
507{
508 // setup
509 if (!Initialize())
510 return false;
511
512 PyGILRAII gilRaii;
513
514 // direct pointer comparison of type member
516}
517
518////////////////////////////////////////////////////////////////////////////////
519/// Extract the object pointer held by the CPPInstance pyobject.
520
522{
523 // setup
524 if (!Initialize())
525 return nullptr;
526
527 PyGILRAII gilRaii;
528
529 // get held object (may be null)
531}
532
533////////////////////////////////////////////////////////////////////////////////
534/// Bind the addr to a python object of class defined by classname.
535
537{
538 // setup
539 if (!Initialize())
540 return nullptr;
541
542 PyGILRAII gilRaii;
543
544 // perform cast (the call will check TClass and addr, and set python errors)
545 // give ownership, for ref-counting, to the python side, if so requested
547}
_object PyObject
ROOT::Detail::TRangeCast< T, true > TRangeDynCast
TRangeDynCast is an adapter class that allows the typed iteration through a TCollection.
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:97
_object PyObject
Definition TPython.h:23
TRObject operator()(const T1 &t1) const
#define gROOT
Definition TROOT.h:411
TClass instances represent classes, structs and namespaces in the ROOT type system.
Definition TClass.h:84
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:2973
Mother of all ROOT objects.
Definition TObject.h:41
static void Prompt()
Enter an interactive python session (exit with ^D).
Definition TPython.cxx:443
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:491
static void * CPPInstance_AsVoidPtr(PyObject *pyobject)
Extract the object pointer held by the CPPInstance pyobject.
Definition TPython.cxx:521
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:339
static Bool_t Import(const char *name)
Import the named python module and create Cling equivalents for its classes and methods.
Definition TPython.cxx:215
static Bool_t CPPInstance_CheckExact(PyObject *pyobject)
Test whether the type of the given pyobject is CPPinstance type.
Definition TPython.cxx:475
static Bool_t Bind(TObject *object, const char *label)
Bind a ROOT object with, at the python side, the name "label".
Definition TPython.cxx:416
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:275
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:383
static Bool_t CPPOverload_CheckExact(PyObject *pyobject)
Test whether the type of the given pyobject is CPPOverload type.
Definition TPython.cxx:506
static Bool_t Initialize()
Initialization method: setup the python interpreter and load the ROOT module.
Definition TPython.cxx:126
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:460
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:536
CPYCPPYY_EXTERN bool Instance_CheckExact(PyObject *pyobject)
Definition API.cxx:177
CPYCPPYY_EXTERN bool Overload_Check(PyObject *pyobject)
Definition API.cxx:236
CPYCPPYY_EXTERN bool Overload_CheckExact(PyObject *pyobject)
Definition API.cxx:247
CPYCPPYY_EXTERN bool Import(const std::string &name)
Definition API.cxx:259
CPYCPPYY_EXTERN void ExecScript(const std::string &name, const std::vector< std::string > &args)
Definition API.cxx:318
CPYCPPYY_EXTERN bool Instance_Check(PyObject *pyobject)
Definition API.cxx:166
CPYCPPYY_EXTERN PyObject * Instance_FromVoidPtr(void *addr, const std::string &classname, bool python_owns=false)
Definition API.cxx:121
CPYCPPYY_EXTERN void * Instance_AsVoidPtr(PyObject *pyobject)
Definition API.cxx:106