test draft

CMakeLists.txt

@@ -528,7 +528,12 @@ if(NOT CMAKE_SOURCE_DIR STREQUAL CMAKE_INSTALL_PREFIX)
   if(webgui)
      install(DIRECTORY ui5/    DESTINATION ${CMAKE_INSTALL_OPENUI5DIR})
   endif()
-  install(DIRECTORY man/    DESTINATION ${CMAKE_INSTALL_MANDIR})
+  if(xproofd AND xrootd AND ssl)
+     set(MAN_PATT_EXCL)
+  else()
+     set(MAN_PATT_EXCL PATTERN xproofd.1 EXCLUDE)
+  endif()
+  install(DIRECTORY man/    DESTINATION ${CMAKE_INSTALL_MANDIR} ${MAN_PATT_EXCL})
   install(DIRECTORY tutorials/ DESTINATION ${CMAKE_INSTALL_TUTDIR} COMPONENT tests)
   install(FILES
     cmake/modules/RootMacros.cmake

README/ReleaseNotes/v624/index.md

@@ -111,3 +111,7 @@ The following people have contributed to this new version:
 ## Build, Configuration and Testing Infrastructure
 
 - a new cmake variable, `CMAKE_INSTALL_PYTHONDIR`, has been added: it allows customization of the installation directory of ROOT's python modules
+
+## PyROOT
+
+- Deprecate `TTree.AsMatrix` in this release and mark for removal in v6.26. Please use instead `RDataFrame.AsNumpy`.

bindings/jupyroot/CMakeLists.txt

@@ -72,8 +72,8 @@ foreach(val RANGE ${how_many_pythons})
   # Install library
   install(TARGETS ${libname} EXPORT ${CMAKE_PROJECT_NAME}Exports
                              RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} COMPONENT libraries
-                             LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT libraries
-                             ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT libraries)
+                             LIBRARY DESTINATION ${CMAKE_INSTALL_PYTHONDIR} COMPONENT libraries
+                             ARCHIVE DESTINATION ${CMAKE_INSTALL_PYTHONDIR} COMPONENT libraries)
 
 endforeach()
 

bindings/pyroot/pythonizations/python/ROOT/__init__.py

@@ -26,6 +26,9 @@
 environ['CPPYY_NO_ROOT_FILTER'] = '1'
 
 import cppyy
+if not 'ROOTSYS' in environ:
+    # Revert setting made by cppyy
+    cppyy.gbl.gROOT.SetBatch(False)
 
 # import libROOTPythonizations with Python version number
 import sys, importlib
@@ -72,10 +75,11 @@ def pythonization_impl(fn):
         module = importlib.import_module(pyz.__name__ + '.' + module_name)
 
 # Check if we are in the IPython shell
-try:
+if major == 3:
     import builtins
-except ImportError:
-    import __builtin__ as builtins # Py2
+else:
+    import __builtin__ as builtins  
+
 _is_ipython = hasattr(builtins, '__IPYTHON__')
 
 # Configure ROOT facade module

bindings/pyroot/pythonizations/python/ROOT/pythonization/_tdirectory.py

@@ -8,6 +8,48 @@
 # For the list of contributors see $ROOTSYS/README/CREDITS.                    #
 ################################################################################
 
+r'''
+/**
+\class TDirectory
+\brief \parblock \endparblock
+\htmlonly
+<div class="pyrootbox">
+\endhtmlonly
+## PyROOT
+
+From Python, it is possible to inspect the content of a TDirectory object
+as if the subdirectories and objects it contains were its attributes.
+Moreover, once a subdirectory or object is accessed for the first time,
+it is cached for later use.
+For example, assuming `d` is a TDirectory instance:
+\code{.py}
+# Access a subdirectory
+d.subdir
+
+# We can go further down in the hierarchy of directories
+d.subdir.subsubdir
+
+# Access an object (e.g. a histogram) in the directory
+d.obj
+
+# ... or in a subdirectory
+d.subdir.obj
+
+# Wrong attribute: raises AttributeError
+d.wrongAttr
+\endcode
+
+Furthermore, TDirectory implements a `WriteObject` Python method which relies
+on TDirectory::WriteObjectAny. This method is a no-op for TDirectory objects,
+but it is useful for objects of TDirectory subclasses such as TDirectoryFile
+and TFile, which inherit it. Please refer to the documentation of those classes
+for more information.
+\htmlonly
+</div>
+\endhtmlonly
+*/
+'''
+
 from libROOTPythonizations import AddDirectoryGetAttrPyz, AddDirectoryWritePyz
 from ROOT import pythonization
 import cppyy

bindings/pyroot/pythonizations/python/ROOT/pythonization/_tdirectoryfile.py

@@ -8,14 +8,64 @@
 # For the list of contributors see $ROOTSYS/README/CREDITS.                    #
 ################################################################################
 
+r'''
+/**
+\class TDirectoryFile
+\brief \parblock \endparblock
+\htmlonly
+<div class="pyrootbox">
+\endhtmlonly
+## PyROOT
+
+In the same way as for TDirectory, it is possible to inspect the content of a
+TDirectoryFile object from Python as if the subdirectories and objects it
+contains were its attributes. For more information, please refer to the
+TDirectory documentation.
+
+In addition to the attribute syntax, one can inspect a TDirectoryFile in Python
+via the `Get` method. In this case, the subdirectory/object name is specified
+as a string:
+\code{.py}
+# Access a subdirectory
+d.Get('subdir')
+
+# We can go further down in the hierarchy of directories
+d.Get('subdir/subsubdir')
+
+# Access an object (e.g. a histogram) in the directory
+d.Get('obj')
+
+# ... or in a subdirectory
+d.Get('subdir/obj')
+
+# Wrong attribute: returns null
+x = d.Get('wrongAttr')  # x points to null
+\endcode
+
+Furthermore, TDirectoryFile inherits a `WriteObject` Python method from
+TDirectory. Such method allows to write an object into a TDirectoryFile
+with the following syntax:
+\code{.py}
+# Write object obj with identifier 'keyName'
+d.WriteObject(obj, 'keyName')
+\endcode
+\htmlonly
+</div>
+\endhtmlonly
+*/
+'''
+
 from libROOTPythonizations import AddTDirectoryFileGetPyz
 from ROOT import pythonization
 
-"""
-TDirectoryFile inherits from TDirectory the pythonized attr syntax (__getattr__)
-and WriteObject method.
-On the other side, the Get() method is pythonised only in TDirectoryFile.
-Thus, the situation is now the following:
+# Pythonizor function
+@pythonization()
+def pythonize_tdirectoryfile(klass, name):
+    """
+    TDirectoryFile inherits from TDirectory the pythonized attr syntax (__getattr__)
+    and WriteObject method.
+    On the other side, the Get() method is pythonised only in TDirectoryFile.
+    Thus, the situation is now the following:
 
     1) __getattr__ : TDirectory --> TDirectoryFile --> TFile
         1.1) caches the returned object for future attempts
@@ -24,12 +74,7 @@
     2) Get() : TDirectoryFile --> TFile
         2.1) does not cache the returned object
         2.2 returns nullptr if object not found
-
-"""
-
-# Pythonizor function
-@pythonization()
-def pythonize_tdirectoryfile(klass, name):
+    """
 
     if name == 'TDirectoryFile':
         AddTDirectoryFileGetPyz(klass)

bindings/pyroot/pythonizations/python/ROOT/pythonization/_tfile.py

@@ -8,10 +8,35 @@
 # For the list of contributors see $ROOTSYS/README/CREDITS.                    #
 ################################################################################
 
-# TFile inherits from
-# - TDirectory the pythonized attr syntax (__getattr__) and WriteObject method.
-# - TDirectoryFile the pythonized Get method (pythonized only in Python)
-# what is left to add is the pythonization of TFile::Open.
+r'''
+/**
+\class TFile
+\brief \parblock \endparblock
+\htmlonly
+<div class="pyrootbox">
+\endhtmlonly
+## PyROOT
+
+In the same way as for TDirectory, it is possible to inspect the content of a
+TFile object from Python as if the directories and objects it contains were its
+attributes. For more information, please refer to the TDirectory documentation.
+
+In addition, TFile instances can be inspected via the `Get` method, a feature
+that is inherited from TDirectoryFile (please see the documentation of
+TDirectoryFile for examples on how to use it).
+
+In order to write objects into a TFile, the `WriteObject` Python method can
+be used (more information in the documentation of TDirectoryFile).
+
+Finally, PyROOT modifies the TFile constructor and the TFile::Open
+method to make them behave in a more pythonic way. In particular,
+they both throw an `OSError` if there was a problem accessing the
+file (e.g. non-existent or corrupted file).
+\htmlonly
+</div>
+\endhtmlonly
+*/
+'''
 
 from libROOTPythonizations import AddFileOpenPyz
 from ROOT import pythonization
@@ -45,6 +70,11 @@ def _TFileOpen(klass, *args):
 # Pythonizor function
 @pythonization()
 def pythonize_tfile(klass, name):
+    """
+    TFile inherits from
+    - TDirectory the pythonized attr syntax (__getattr__) and WriteObject method.
+    - TDirectoryFile the pythonized Get method (pythonized only in Python)
+    """
 
     if name == 'TFile':
         # Pythonizations for TFile::Open

bindings/pyroot/pythonizations/python/ROOT/pythonization/_ttree.py

@@ -8,6 +8,128 @@
 # For the list of contributors see $ROOTSYS/README/CREDITS.                    #
 ################################################################################
 
+r'''
+/**
+\class TTree
+\brief \parblock \endparblock
+\htmlonly
+<div class="pyrootbox">
+\endhtmlonly
+## PyROOT
+
+The TTree class has several additions for its use from Python, which are also
+available in its subclasses e.g. TChain and TNtuple.
+
+First, TTree instances are iterable in Python. Therefore, assuming `t` is
+a TTree instance, we can do:
+\code{.py}
+for entry in t:
+    x = entry.branch_name
+    ...
+\endcode
+
+At each iteration, a new entry of the tree will be read. In the code above,
+`entry` allows to access the branch values for the current entry. This can be
+done with the syntax `entry.branch_name` or, if the branch name is incompatible
+with Python naming rules, with e.g. "getattr(entry, '1_branch_name')".
+
+<em>Please note</em> that iterating in Python can be slow, so only iterate over
+a tree as described above if performance is not an issue or when dealing with
+a small dataset. To read and process the entries of a tree in a much faster
+way, please use ROOT::RDataFrame.
+
+Second, a couple of TTree methods have been modified to facilitate their use
+from Python: TTree::Branch and TTree::SetBranchAddress.
+
+Regarding TTree::Branch, the following example shows how we can create
+different types of branches of a TTree. Note that `Branch` will just link
+the new branch with a given Python object, so it is still necessary to fill
+such object with the desired content before calling TTree::Fill.
+\code{.py}
+from array import array
+import numpy as np
+import ROOT
+from ROOT import addressof
+
+# Basic type branch (float) - use array of length 1
+n = array('f', [ 1.5 ])
+t.Branch('floatb', n, 'floatb/F')
+
+# Array branch - use array of length N
+N = 10
+a = array('d', N*[ 0. ])
+t.Branch('arrayb', a, 'arrayb[' + str(N) + ']/D')
+
+# Array branch - use NumPy array of length N
+npa = np.array(N*[ 0. ])
+t.Branch('nparrayb', npa, 'nparrayb[' + str(N) + ']/D')
+
+# std::vector branch
+v = ROOT.std.vector('double')(N*[ 0. ])
+t.Branch('vectorb0', v)
+
+# Class branch / struct in single branch
+cb = ROOT.MyClass()
+t.Branch('classb', cb)
+
+# Struct as leaflist
+# Assuming:
+# struct MyStruct {
+#   int myint;
+#   float myfloat;
+# };
+ms = ROOT.MyStruct()
+t.Branch('structll', ms, 'myint/I:myfloat/F')
+
+# Store struct members individually
+ms = ROOT.MyStruct()
+# Use `addressof` to get the address of the struct members
+t.Branch('myintb', addressof(ms, 'myint'), 'myint/I')
+t.Branch('myfloatb', addressof(ms, 'myfloat'), 'myfloat/F')
+\endcode
+
+Concerning TTree::SetBranchAddress, below is an example of prepare
+the reading of different types of branches of a TTree. Note that
+`SetBranchAddress` will just link a given branch with a certain
+Python object; after that, in order to read the content of such
+branch for a given TTree entry `x`, TTree::GetEntry(x) must be
+invoked.
+\code{.py}
+from array import array
+import numpy as np
+import ROOT
+
+# Basic type branch (float) - use array of length 1
+n = array('f', [ 0. ])
+t.SetBranchAddress('floatb', n)
+
+# Array branch - use array of length N
+N = 10
+a = array('d', N*[ 0. ])
+t.SetBranchAddress('arrayb', a)
+
+# Array branch - use NumPy array of length N
+npa = np.array(N*[ 0. ])
+t.SetBranchAddress('nparrayb', a)
+
+# std::vector branch
+v = ROOT.std.vector('double')()
+t.SetBranchAddress('vectorb', v)
+
+# Class branch
+cb = ROOT.MyClass()
+t.SetBranchAddress('classb', cb)
+
+# Struct branch (both single-branch and leaf list)
+ms = ROOT.MyStruct()
+ds.SetBranchAddress('structb', ms)
+\endcode
+\htmlonly
+</div>
+\endhtmlonly
+*/
+'''
+
 from libROOTPythonizations import AddBranchAttrSyntax, SetBranchAddressPyz, BranchPyz
 
 import cppyy
@@ -65,6 +187,9 @@ def _TTreeAsMatrix(self, columns=None, exclude=None, dtype="double", return_labe
         array(, labels): Numpy array(, labels of columns)
     """
 
+    import warnings
+    warnings.warn("TTree.AsMatrix is deprecated since v6.24 and will be removed in v6.26. Please use instead RDataFrame.AsNumpy.", FutureWarning)
+
     # Import numpy lazily
     try:
         import numpy as np

bindings/pyroot/pythonizations/src/PyzCppHelpers.cxx

@@ -43,7 +43,7 @@ PyObject *BoolNot(PyObject *value)
 // Get the TClass of the C++ object proxied by pyobj
 TClass *GetTClass(const CPyCppyy::CPPInstance *pyobj)
 {
-   return TClass::GetClass(Cppyy::GetFinalName(pyobj->ObjectIsA()).c_str());
+   return TClass::GetClass(Cppyy::GetScopedFinalName(pyobj->ObjectIsA()).c_str());
 }
 
 ////////////////////////////////////////////////////////////////////////////