TPython Class Reference

Accessing the Python interpreter from C++.

The TPython class allows for access to python objects from Cling. The current functionality is only basic: ROOT objects and builtin types can freely cross the boundary between the two interpreters, python objects can be instantiated and their methods can be called. All other cross-coding is based on strings that are run on the python interpreter.

Examples:

$ root -l
// Execute a string of python code.
root [0] TPython::Exec( "print('Hello World!')" );
Hello World!
 
// Create a TNamed on the python side, and transfer it back and forth.
root [1] std::any res1;
root [2] TPython::Exec("_anyresult = ROOT.std.make_any['TNamed']('hello', '')", &res1);
root [3] TPython::Bind(&std::any_cast<TNamed&>(res1), "n");
root [4] std::any res2;
root [5] TPython::Exec("_anyresult = ROOT.std.make_any['TNamed*', 'TNamed*'](n)", &res2);
root [6] (&std::any_cast<TNamed&>(res1) == std::any_cast<TNamed*>(res2))
(bool) true
 
// Variables can cross-over by using an `std::any` with a specific name.
root [6] TPython::Exec("_anyresult = ROOT.std.make_any['Int_t'](1 + 1)", &res1);
root [7] std::any_cast<int>(res1)
(int) 2

And with a python file MyPyClass.py like this:

print 'creating class MyPyClass ... '
 
class MyPyClass:
   def __init__( self ):
      print 'in MyPyClass.__init__'
 
   def gime( self, what ):
      return what

one can load a python module, and use the class. Casts are necessary as the type information can not be otherwise derived.

root [6] TPython::LoadMacro( "MyPyClass.py" );
creating class MyPyClass ...
root [7] MyPyClass m;
in MyPyClass.__init__
root [8] std::string s = (char*)m.gime( "aap" );
root [9] s
(class TString)"aap"

It is possible to switch between interpreters by calling TPython::Prompt() on the Cling side, while returning with ^D (EOF). State is preserved between successive switches.

The API part provides (direct) C++ access to the bindings functionality of PyROOT. It allows verifying that you deal with a PyROOT python object in the first place (CPPInstance_Check for CPPInstance and any derived types, as well as CPPInstance_CheckExact for CPPInstance's only); and it allows conversions of void* to an CPPInstance and vice versa.

Definition at line 44 of file TPython.h.

Static Public Member Functions
static const TPyReturn	Eval (const char *expr) R__DEPRECATED(6
	Evaluate a python expression (e.g.
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.
static void	ExecScript (const char *name, int argc=0, const char **argv=nullptr)
	Execute a python stand-alone script, with argv CLI arguments.
static Bool_t	Import (const char *name)
	Import the named python module and create Cling equivalents for its classes and methods.
static void	LoadMacro (const char *name)
	Execute the give python script as if it were a macro (effectively an execfile in main), and create Cling equivalents for any newly available python classes.

Static Private Member Functions
static Bool_t	Initialize ()
	Initialization method: setup the python interpreter and load the ROOT module.

#include <TPython.h>

Member Function Documentation

Eval()

const TPyReturn TPython::Eval ( const char *  expr )

static

Evaluate a python expression (e.g.

"ROOT.TBrowser()").

Caution: do not hold on to the return value: either store it in a builtin type (implicit casting will work), or in a pointer to a ROOT object (explicit casting to a void* is required).

Deprecated:

Use TPython::Exec() with an std::any output parameter instead.

Definition at line 439 of file TPython.cxx.

Exec()

Bool_t TPython::Exec ( const char *  cmd, std::any *  result = nullptr, std::string const &  resultName = "_anyresult"  )

static

Executes a Python command within the current Python environment.

This function initializes the Python environment if it is not already initialized. It then executes the specified Python command string using the Python C API.

In the Python command, you can change the value of a special TPyResult object returned by TPyBuffer(). If the optional result parameter is non-zero, the result parameter will be swapped with a std::any variable on the Python side. You need to define this variable yourself, and it needs to be of type std::any and its name needs to be "_anyresult" by default. Like this, you can pass information from Python back to C++.

Parameters

cmd	The Python command to be executed as a string.
result	Optional pointer to a std::any object that can be used to transfer results from Python to C++.
resultName	Name of the Python variable that is swapped over to the std::any result. The default value is "_anyresult".

Returns

bool Returns true if the command was successfully executed, otherwise returns false.

Definition at line 403 of file TPython.cxx.

ExecScript()

void TPython::ExecScript ( const char *  name, int  argc = 0, const char **  argv = nullptr  )

static

Execute a python stand-alone script, with argv CLI arguments.

example of use: const char* argv[] = { "1", "2", "3" }; TPython::ExecScript( "test.py", sizeof(argv)/sizeof(argv[0]), argv );

Definition at line 361 of file TPython.cxx.

Import()

Bool_t TPython::Import ( const char *  name )

static

Import the named python module and create Cling equivalents for its classes and methods.

Definition at line 233 of file TPython.cxx.

Initialize()

Bool_t TPython::Initialize ( )

staticprivate

Initialization method: setup the python interpreter and load the ROOT module.

Definition at line 147 of file TPython.cxx.

LoadMacro()

void TPython::LoadMacro ( const char *  name )

static

Execute the give python script as if it were a macro (effectively an execfile in main), and create Cling equivalents for any newly available python classes.

Definition at line 291 of file TPython.cxx.

---

The documentation for this class was generated from the following files:

• bindings/tpython/inc/TPython.h
• bindings/tpython/src/TPython.cxx