doc/v626/pyroot002__pythonizationDecorator_8py.html

import ROOT

from ROOT import pythonization


# Let's first define a new C++ class. In this tutorial, we will see how we can

# "pythonize" this class, i.e. how we can add some extra behaviour to it to

# make it more pythonic or easier to use from Python.

#

# Note: In this example, the class is defined dynamically for demonstration

# purposes, but it could also be a C++ class defined in some library or header.

# For more information about loading C++ user code to be used from Python with

# PyROOT, please see:

# https://root.cern.ch/manual/python/#loading-user-libraries-and-just-in-time-compilation-jitting

ROOT.gInterpreter.Declare('''

class MyClass {};

''')


# Next, we define a pythonizor function: the function that will be responsible

# for injecting new behaviour in our C++ class `MyClass`.

#

# To convert a given Python function into a pythonizor, we need to decorate it

# with the @pythonization decorator. Such decorator allows us to define which

# which class we want to pythonize by providing its class name and its

# namespace (if the latter is not specified, it defaults to the global

# namespace, i.e. '::').

#

# The decorated function - the pythonizor - must accept either one or two

# parameters:

# 1. The class to be pythonized (proxy object where new behaviour can be

# injected)

# 2. The fully-qualified name of that class (optional).

#

# Let's see all this with a simple example. Suppose I would like to define how

# `MyClass` objects are represented as a string in Python (i.e. what would be

# shown when I print that object). For that purpose, I can define the following

# pythonizor function. There are two important things to be noted here:

# - The @pythonization decorator has one argument that specifies our target

# class is `MyClass`.

# - The pythonizor function `pythonizor_of_myclass` provides and injects a new

# implementation for `__str__`, the mechanism that Python provides to define

# how to represent objects as strings. This new implementation

# always returns the string "This is a MyClass object".

@pythonization('MyClass')

def pythonizor_of_myclass(klass):

    klass.__str__ = lambda o : 'This is a MyClass object'


# Once we have defined our pythonizor function, let's see it in action.

# We will now use the `MyClass` class for the first time from Python: we will

# create a new instance of that class. At this moment, the pythonizor will

# execute and modify the class - pythonizors are always lazily run when a given

# class is used for the first time from a Python script.

my_object = ROOT.MyClass()


# Since the pythonizor already executed, we should now see the new behaviour.

# For that purpose, let's print `my_object` (should show "This is a MyClass

# object").

print(my_object)


# The previous example is just a simple one, but there are many ways in which a

# class can be pythonized. Typical examples are the redefinition of dunder

# methods (e.g. `__iter__` and `__next__` to make your objects iterable from

# Python). If you need some inspiration, many ROOT classes are pythonized in

# the way we just saw; their pythonizations can be seen at:

# https://github.com/root-project/root/tree/master/bindings/pyroot/pythonizations/python/ROOT/pythonization


# The @pythonization decorator offers a few more options when it comes to

# matching classes that you want to pythonize. We saw that we can match a

# single class, but we can also specify a list of classes to pythonize.

#

# The following code defines a couple of new classes:

ROOT.gInterpreter.Declare('''

namespace NS {

    class Class1 {};

    class Class2 {};

}

''')


# Note that these classes belong to the `NS` namespace. As mentioned above, the

# @pythonization decorator accepts a parameter with the namespace of the class

# or classes to be pythonized. Therefore, a pythonizor that matches both classes

# would look like this:

@pythonization(['Class1', 'Class2'], ns='NS')

def pythonize_two_classes(klass):

    klass.new_attribute = 1


# Both classes will have the new attribute:

o1 = ROOT.NS.Class1()

o2 = ROOT.NS.Class2()

print("Printing new attribute")

for o in o1, o2:

    print(o.new_attribute)


# In addition, @pythonization also accepts prefixes of classes in a certain

# namespace in order to match multiple classes in that namespace. To signal that

# what we provide to @pythonization is a prefix, we need to set the `is_prefix`

# argument to `True` (default is `False`).

#

# A common case where matching prefixes is useful is when we have a templated

# class and we want to pythonize all possible instantiations of that template.

# For example, we can pythonize the `std::vector` (templated) class like so:

@pythonization('vector<', ns='std', is_prefix=True)

def vector_pythonizor(klass):

    # first_elem returns the first element of the vector if it exists

    klass.first_elem = lambda v : v[0] if v else None


# Since we defined a prefix to do the match, the pythonization will be applied

# both if we instantiate e.g. a vector of integers and a vector of doubles.

v_int = ROOT.std.vector['int']([1,2,3])

v_double = ROOT.std.vector['double']([4.,5.,6.])

print("First element of integer vector: {}".format(v_int.first_elem()))

print("First element of double vector: {}".format(v_double.first_elem()))


# Note that specifying a list of class name prefixes is also possible (similarly

# to what we saw with a list of class names). Again, `is_prefix=True` is

# required to signal that we are providing a list of prefixes.


# These are some examples of combinations of prefixes and namespaces and the

# corresponding classes that they match:

# - '' : all classes in the global namespace.

# - '', ns='NS1::NS2' : all classes in the `NS1::NS2` namespace.

# - 'Prefix' : classes whose name starts with `Prefix` in the global namespace.

# - 'Prefix', ns='NS' : classes whose name starts with `Prefix` in the `NS`

# namespace.


# Moreover, a pythonizor function can have a second optional parameter that

# contains the fully-qualified name of the class being pythonized. This can be

# useful e.g. if we would like to do some more complex filtering of classes in

# our pythonizor, for instance using regular expressions.

@pythonization('pair<', ns='std', is_prefix=True)

def pair_pythonizor(klass, name):

    print('Pythonizing class ' + name)


# The pythonizor above will be applied to any instantiation of `std::pair` - we

# can see this with the print we did inside the pythonizor.

# Note that we could use the `name` parameter to e.g. further filter which

# particular instantiations we would like to pythonize.

p1 = ROOT.std.pair['int','int'](1,2) # prints 'Pythonizing class std::pair<int,int>'

p2 = ROOT.std.pair['int','double'](1,2.) # prints 'Pythonizing class std::pair<int,double>'


# Note that, to pythonize multiple classes in different namespaces, we can

# stack multiple @pythonization decorators. For example, if we define these

# classes:

ROOT.gInterpreter.Declare('''

class FirstClass {};

namespace NS {

    class SecondClass {};

}

''')


# We can pythonize both of them with a single pythonizor function like so:

@pythonization('FirstClass')

@pythonization('SecondClass', ns='NS')

def pythonizor_for_first_and_second(klass, name):

    print('Executed for class ' + name)


# If we now access both classes, we should see that the pythonizor runs twice.

f = ROOT.FirstClass()

s = ROOT.NS.SecondClass()


# So far we have seen how pythonizations can be registered for classes that

# have not been used yet. We have discussed how, in that case, the pythonizor

# functions are executed lazily when their target class/es are used for the

# first time in the application.

# However, it can also happen that our target class/es have already been

# accessed by the time we register a pythonization. In such a scenario, the

# pythonizor is applied immediately (at registration time) to the target

# class/es.


# Let's see an example of what was just explained. We will define a new class

# and immediately create an object of that class. We can check how the object

# still does not have a new attribute `pythonized` that we are going to inject

# in the next step.

ROOT.gInterpreter.Declare('''

class MyClass2 {};

''')

o = ROOT.MyClass2()

try:

    print(o.pythonized)

except AttributeError:

    print("Object has not been pythonized yet!")


# After that, we will register a pythonization for `MyClass2`. Since the class

# has already been used, the pythonization will happen right away.

@pythonization('MyClass2')

def pythonizor_for_myclass2(klass):

    klass.pythonized = True


# Now our object does have the `pythonized` attribute:

print(o.pythonized) # prints True