ROOT I/O

The uproot.rootio module contains everything needed to navigate through a ROOT file and extract inert, data-only objects. Methods for those objects are defined in other modules. The uproot.open function returns a ROOTDirectory object, which is a handle into the file, from which all other data can be accessed.

This module has many more classes than those documented here, but all but a few are considered internal details. The classes documented below represent the public API. In fact, only ROOTDirectory has useful attributes and methods for a typical user. The other two, ROOTObject and ROOTStreamedObject, are documented because they are superclasses of all objects that could be extracted from a ROOT file, and may be useful in isinstance checks.

uproot.rootio.ROOTDirectory

Although ROOTDirectory resembles ROOT’s TFile, TDirectory, and TFileDirectory to some degree, it does not have a direct relationship to any of them. (This is because we adopted a different model for representing the contents of a ROOT file: purely acyclic with continuation passing.) As a result, ROOTDirectory is not a ROOTObject and isn’t named “TFile.”

A ROOTDirectory may represent a whole ROOT file or a single TDirectory within that file— after reading, there is no difference.

class uproot.rootio.ROOTDirectory(name, context, keys)

Represents a ROOT file or directory, an entry point for reading objects.

Although this class has a constructor that could be called by a user, objects are usually created from ROOT files through open or xrootd.

ROOTDirectory objects may be accessed as Python containers:

• square brackets (__getitem__) read objects from the file by key name (see get).
• the len function (__len__) returns the number of keys.
• iteration (__iter__) iterates over the names of the keys only (like a dict, see keys).

Attributes, properties, and methods:

• name (bytes) name of the file or directory as read from the ROOT file. (ROOT files may be imprinted with a different name than they have in the file system.)
• compression (Compression) the compression algorithm and level specified in the file header. (Some objects, including TTree branches, may have different compression settings than the global file settings.)
• get read an object from the file, selected by name.
• iterkeys iterate over key names in this directory.
• itervalues iterate over objects in this directory.
• iteritems iterate over (key name, object) pairs in this directory, like a dict.
• iterclasses iterate over (key name, class object) pairs in this directory.
• keys return key names in this directory.
• values return objects in this directory.
• items return (key name, object) pairs in this directory, like a dict.
• classes return (key name, class object) pairs in this directory.
• allkeys return keys at all levels of depth (shortcut for passing recursive=True to keys).
• allvalues return objects at all levels of depth (shortcut for passing recursive=True to values).
• allitems return (key name, object) pairs at all levels of depth (shortcut for passing recursive=True to items).
• allclasses return (key name, class object) pairs at all levels of depth (shortcut for passing recursive=True to classes).

ROOTDirectory.get(name, cycle=None)

Read an object from the ROOT file or directory by name.

Parameters:

• name (str (str)) – name of the object. Any text before a “/” is interpreted as a subdirectory, and subdirectories of any depth may be searched. A number after a “;” indicates a TKey <uproot.rootio.TKey> cycle.
• cycle (None or int) – TKey <uproot.rootio.TKey> cycle number to disambiguate keys of the same name. This argument overrides a number after a “;”.

Returns:

a freshly read object from the ROOT file.

Return type:

ROOTStreamedObject

Notes

This method, without the cycle argument, can be accessed more directly through square brackets (__getitem__) on the ROOTDirectory object.

ROOTDirectory.iterkeys(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)

Iterate over key names in this directory.

This method does not read objects.

Parameters:

• recursive (bool) – if False (default), only iterate over this directory level; if True, depth-first iterate over all subdirectories as well.
• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

names of objects and subdirectories in the file.

Return type:

iterator over bytes

Notes

This method can be accessed more directly by simply iterating over a ROOTDirectory object.

ROOTDirectory.itervalues(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)

Iterate over objects in this directory.

Parameters:

• recursive (bool) – if False (default), only iterate over this directory level; if True, depth-first iterate over all subdirectories as well.
• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

freshly read objects from the ROOT file.

Return type:

iterator over ROOTStreamedObject

ROOTDirectory.iteritems(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)

Iterate over (key name, object) pairs in this directory, like a dict.

Parameters:

• recursive (bool) – if False (default), only iterate over this directory level; if True, depth-first iterate over all subdirectories as well.
• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

name-object pairs from the file.

Return type:

iterator over (bytes, ROOTStreamedObject)

ROOTDirectory.iterclasses(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)

Iterate over (key name, class object) pairs in this directory.

This method does not read objects.

Parameters:

• recursive (bool) – if False (default), only iterate over this directory level; if True, depth-first iterate over all subdirectories as well.
• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

name-class object pairs from the file.

Return type:

iterator over (bytes, class object)

ROOTDirectory.keys(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)

Return key names in this directory.

This method does not read objects.

Parameters:

• recursive (bool) – if False (default), only iterate over this directory level; if True, depth-first iterate over all subdirectories as well.
• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

names of objects and subdirectories in the file.

Return type:

list of bytes

ROOTDirectory.values(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)

Return objects in this directory.

Parameters:

• recursive (bool) – if False (default), only iterate over this directory level; if True, depth-first iterate over all subdirectories as well.
• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

freshly read objects from the ROOT file.

Return type:

list of ROOTStreamedObject

ROOTDirectory.items(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)

Return (key name, object) pairs in this directory, like a dict.

Parameters:

• recursive (bool) – if False (default), only iterate over this directory level; if True, depth-first iterate over all subdirectories as well.
• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

name-object pairs from the file.

Return type:

list of (bytes, ROOTStreamedObject)

ROOTDirectory.classes(recursive=False, filtername=<function nofilter>, filterclass=<function nofilter>)

Return (key name, class object) pairs in this directory.

This method does not read objects.

Parameters:

• recursive (bool) – if False (default), only iterate over this directory level; if True, depth-first iterate over all subdirectories as well.
• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

name-class object pairs from the file.

Return type:

list of (bytes, class object)

ROOTDirectory.allkeys(filtername=<function nofilter>, filterclass=<function nofilter>)

Return keys at all levels of depth (shortcut for passing recursive=True to keys).

This method does not read objects.

Parameters:

• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

names of objects and subdirectories in the file.

Return type:

list of bytes

ROOTDirectory.allvalues(filtername=<function nofilter>, filterclass=<function nofilter>)

Return objects at all levels of depth (shortcut for passing recursive=True to values).

Parameters:

• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

freshly read objects from the ROOT file.

Return type:

list of ROOTStreamedObject

ROOTDirectory.allitems(filtername=<function nofilter>, filterclass=<function nofilter>)

Return (key name, object) pairs at all levels of depth (shortcut for passing recursive=True to items).

Parameters:

• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

name-object pairs from the file.

Return type:

list of (bytes, ROOTStreamedObject)

ROOTDirectory.allclasses(filtername=<function nofilter>, filterclass=<function nofilter>)

Return (key name, class object) pairs at all levels of depth (shortcut for passing recursive=True to classes).

This method does not read objects.

Parameters:

• filtername (function: str ⇒ bool) – only keys for which filtername(name) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input.
• filterclass (function: class object ⇒ bool) – only keys for which filterclass(class object) returns True are returned (does not eliminate subdirectories if recursive=True). Default returns True for all input. Note that all class objects passed to this function have a classname attribute for the C++ class name (may differ from the Python class name for syntactic reasons).

Returns:

name-class object pairs from the file.

Return type:

list of (bytes, class object)

uproot.rootio.ROOTObject

class uproot.rootio.ROOTObject

Superclass of all objects read out of a ROOT file (except ROOTDirectory).

If a ROOTObject is not a ROOTStreamedObject, then its class definition is hard-coded, not derived from the file’s streamer info.

uproot.rootio.ROOTStreamedObject

class uproot.rootio.ROOTStreamedObject

Superclass of all objects read out of a ROOT file with an automatically generated class, derived from the file’s streamer info.

Each subclass of a ROOTStreamedObject has a classversion attribute, corresponding to the class version in the streamer info. If this version does not match the version of the serialized class, an error is raised during the read.