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 36 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 74 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 404 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 75 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 509 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 448 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 463 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 524 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 479 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 494 of file TPython.cxx.

◆ DeclFileName()

static const char * TPython::DeclFileName ( )

inlinestatic

Returns: Name of the file containing the class declaration

Definition at line 75 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 380 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 336 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 198 of file TPython.cxx.

◆ Initialize()

Bool_t TPython::Initialize ( )

staticprivate

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

Definition at line 128 of file TPython.cxx.

◆ IsA()

virtual TClass * TPython::IsA ( ) const

inlinevirtual

Returns: TClass describing current object

Definition at line 75 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 258 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 431 of file TPython.cxx.

◆ Streamer()

virtual void TPython::Streamer ( TBuffer & )

virtual

◆ StreamerNVirtual()

inline

Definition at line 75 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

Sunbelt Computer Software

PL/B Language Development and Support

Public Member Functions

Static Public Member Functions

Static Private Member Functions

Constructor & Destructor Documentation

◆ ~TPython()

Member Function Documentation

◆ Bind()

◆ Class()

◆ Class_Name()

◆ Class_Version()

◆ CPPInstance_AsVoidPtr()

◆ CPPInstance_Check()

◆ CPPInstance_CheckExact()

◆ CPPInstance_FromVoidPtr()

◆ CPPOverload_Check()

◆ CPPOverload_CheckExact()

◆ DeclFileName()

◆ Exec()

◆ ExecScript()

◆ Import()

◆ Initialize()

◆ IsA()

◆ LoadMacro()

◆ Prompt()

◆ Streamer()

◆ StreamerNVirtual()