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 43 of file TPython.h.

Public Member Functions
virtual	~TPython ()
virtual TClass *	IsA () const
virtual void	Streamer (TBuffer &)
void	StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)

Static Public Member Functions
static Bool_t	Bind (TObject *object, const char *label)
	Bind a ROOT object with, at the python side, the name "label".
static TClass *	Class ()
static const char *	Class_Name ()
static constexpr Version_t	Class_Version ()
static void *	CPPInstance_AsVoidPtr (PyObject *pyobject)
	Extract the object pointer held by the CPPInstance pyobject.
static Bool_t	CPPInstance_Check (PyObject *pyobject)
	Test whether the type of the given pyobject is of CPPInstance type or any derived type.
static Bool_t	CPPInstance_CheckExact (PyObject *pyobject)
	Test whether the type of the given pyobject is CPPinstance type.
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.
static Bool_t	CPPOverload_Check (PyObject *pyobject)
	Test whether the type of the given pyobject is of CPPOverload type or any derived type.
static Bool_t	CPPOverload_CheckExact (PyObject *pyobject)
	Test whether the type of the given pyobject is CPPOverload type.
static const char *	DeclFileName ()
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 void	Prompt ()
	Enter an interactive python session (exit with ^D).

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

#include <TPython.h>

Constructor & Destructor Documentation

~TPython()

virtual TPython::~TPython ( )

inlinevirtual

Definition at line 81 of file TPython.h.

Member Function Documentation

Bind()

Bool_t TPython::Bind ( TObject *  object, const char *  label  )

static

Bind a ROOT object with, at the python side, the name "label".

Definition at line 459 of file TPython.cxx.

Class()

static TClass * TPython::Class ( )

static

Returns

TClass describing this class

Class_Name()

static const char * TPython::Class_Name ( )

static

Returns

Name of this class

Class_Version()

static constexpr Version_t TPython::Class_Version ( )

inlinestaticconstexpr

Returns

Version of this class

Definition at line 82 of file TPython.h.

CPPInstance_AsVoidPtr()

void * TPython::CPPInstance_AsVoidPtr ( PyObject *  pyobject )

static

Extract the object pointer held by the CPPInstance pyobject.

Definition at line 565 of file TPython.cxx.

CPPInstance_Check()

Bool_t TPython::CPPInstance_Check ( PyObject *  pyobject )

static

Test whether the type of the given pyobject is of CPPInstance type or any derived type.

Definition at line 504 of file TPython.cxx.

CPPInstance_CheckExact()

Bool_t TPython::CPPInstance_CheckExact ( PyObject *  pyobject )

static

Test whether the type of the given pyobject is CPPinstance type.

Definition at line 519 of file TPython.cxx.

CPPInstance_FromVoidPtr()

PyObject * TPython::CPPInstance_FromVoidPtr ( void *  addr, const char *  classname, Bool_t  python_owns = kFALSE  )

static

Bind the addr to a python object of class defined by classname.

Definition at line 580 of file TPython.cxx.

CPPOverload_Check()

Bool_t TPython::CPPOverload_Check ( PyObject *  pyobject )

static

Test whether the type of the given pyobject is of CPPOverload type or any derived type.

Definition at line 535 of file TPython.cxx.

CPPOverload_CheckExact()

Bool_t TPython::CPPOverload_CheckExact ( PyObject *  pyobject )

static

Test whether the type of the given pyobject is CPPOverload type.

Definition at line 550 of file TPython.cxx.

DeclFileName()

static const char * TPython::DeclFileName ( )

inlinestatic

Returns

Name of the file containing the class declaration

Definition at line 82 of file TPython.h.

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 425 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 381 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 237 of file TPython.cxx.

Initialize()

Bool_t TPython::Initialize ( )

staticprivate

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

Definition at line 137 of file TPython.cxx.

IsA()

virtual TClass * TPython::IsA ( ) const

inlinevirtual

Returns

TClass describing current object

Definition at line 82 of file TPython.h.

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 305 of file TPython.cxx.

Prompt()

void TPython::Prompt ( )

static

Enter an interactive python session (exit with ^D).

State is preserved between successive calls.

Definition at line 487 of file TPython.cxx.

Streamer()

virtual void TPython::Streamer ( TBuffer &  )

virtual

StreamerNVirtual()

void TPython::StreamerNVirtual ( TBuffer &  ClassDef_StreamerNVirtual_b )

inline

Definition at line 82 of file TPython.h.

---

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

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