uproot.ReadOnlyDirectory

Defined in uproot.reading on line 1260.

Inheritance order:

  1. collections.abc.Mapping

  2. collections.abc.Collection

  3. collections.abc.Sized

  4. collections.abc.Iterable

  5. collections.abc.Container

class uproot.reading.ReadOnlyDirectory(path, cursor, context, file, parent)
Parameters:
  • path (tuple of str) – Object path of the TDirectory as a tuple of nested TDirectory names.

  • cursor (uproot.Cursor) – Current position in the uproot.ReadOnlyFile.

  • context (dict) – Auxiliary data used in deserialization.

  • file (uproot.ReadOnlyFile) – The open file object.

  • parent (None or calling object) – The previous read in the recursive descent.

Represents a TDirectory from a ROOT file, most notably, the root directory (root_directory).

Be careful not to confuse uproot.ReadOnlyFile and uproot.ReadOnlyDirectory: files are for accessing global information such as streamers and directories are for data in local hierarchies.

A uproot.ReadOnlyDirectory is a Python Mapping, which uses square bracket syntax to extract objects:

my_directory["histogram"]
my_directory["tree"]
my_directory["directory"]["another_tree"]

Objects in ROOT files also have “cycle numbers,” which allow multiple versions of an object to be retrievable using the same name. A cycle number may be specified after a semicolon:

my_directory["histogram;2"]

but without one, the directory defaults to the latest (highest cycle number).

It’s also possible to navigate through nested directories with a slash (/) instead of sequences of square brackets. The following are equivalent:

my_directory["directory"]["another_tree"]["branch_in_tree"]  # long form
my_directory["directory/another_tree"]["branch_in_tree"]     # / for dir
my_directory["directory/another_tree/branch_in_tree"]        # / for branch
my_directory["/directory/another_tree/branch_in_tree"]       # absolute
my_directory["/directory////another_tree/branch_in_tree"]    # extra ///

As a Python Mapping, uproot.ReadOnlyDirectory also has

  • keys: names of objects in the TDirectory

  • values: objects in the TDirectory

  • items: 2-tuple (name, object) pairs.

However, the uproot.ReadOnlyDirectory versions of these methods have extra parameters for navigating a complex ROOT file. In addition, there is a

  • classnames: returns a dict of (name, classname) pairs.

with the same parameters.

See the ROOT TDirectoryFile documentation for a specification of TDirectory header fields (in an image).

path

ReadOnlyDirectory.path

Object path of the TDirectory as a tuple of nested TDirectory names. The root directory is an empty tuple, ().

See object_path for the path as a string.

object_path

ReadOnlyDirectory.object_path

Object path of the TDirectory as a single string, beginning and ending with /. The root directory is a single slash, "/".

See path for the path as a tuple of strings.

file_path

ReadOnlyDirectory.file_path

The original path to the file (converted to str if it was originally a pathlib.Path).

file

ReadOnlyDirectory.file

The uproot.ReadOnlyFile in which this TDirectory resides.

This property is useful for getting global information, in idioms like

with uproot.open("/path/to/file.root") as handle:
    handle.file.show_streamers()

close

ReadOnlyDirectory.close()

Close the uproot.ReadOnlyFile in which this TDirectory resides.

closed

ReadOnlyDirectory.closed

True if the file is closed; False otherwise.

created_on

ReadOnlyDirectory.created_on

Creation date/time as a Python datetime.

fDatimeC presents this in ROOT’s raw integer encoding.

modified_on

ReadOnlyDirectory.modified_on

Modification date/time as a Python datetime.

fDatimeM presents this in ROOT’s raw integer encoding.

cursor

ReadOnlyDirectory.cursor

A uproot.Cursor pointing to the seek point in the file where this TDirectory is defined (at the start of the TDirectory header).

parent

ReadOnlyDirectory.parent

The object that was deserialized before this one in recursive descent, usually the containing object (or the container’s container).

is_64bit

ReadOnlyDirectory.is_64bit

True if the TDirectory is 64-bit ready; False otherwise.

This refers to seek points like fSeekDir being 64-bit integers, rather than 32-bit.

Note that a file being 64-bit is distinct from a TDirectory being 64-bit; see is_64bit.

cache_key

ReadOnlyDirectory.cache_key

String that uniquely specifies this TDirectory path, to use as part of object and array cache keys.

keys

ReadOnlyDirectory.keys(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
Parameters:
  • recursive (bool) – If True, descend into any nested subdirectories. If False, only return the names of objects directly accessible in this TDirectory.

  • cycle (bool) – If True, include the cycle numbers in those names.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by name.

  • filter_classname (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

Returns the names of the objects in this TDirectory as a list of strings.

Note that this does not read any data from the file.

values

ReadOnlyDirectory.values(*, recursive=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
Parameters:
  • recursive (bool) – If True, descend into any nested subdirectories. If False, only return objects directly accessible in this TDirectory.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by name.

  • filter_classname (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

Returns objects in this TDirectory as a list of uproot.Model.

Note that this reads all objects that are selected by filter_name and filter_classname.

items

ReadOnlyDirectory.items(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
Parameters:
  • recursive (bool) – If True, descend into any nested subdirectories. If False, only return (name, object) pairs directly accessible in this TDirectory.

  • cycle (bool) – If True, include the cycle numbers in the names.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by name.

  • filter_classname (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

Returns (name, object) pairs for objects in this TDirectory as a list of 2-tuples of (str, uproot.Model).

Note that this reads all objects that are selected by filter_name and filter_classname.

classnames

ReadOnlyDirectory.classnames(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
Parameters:
  • recursive (bool) – If True, descend into any nested subdirectories. If False, only return the names and classnames of objects directly accessible in this TDirectory.

  • cycle (bool) – If True, include the cycle numbers in the names.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by name.

  • filter_classname (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

Returns the names and C++ (decoded) classnames of the objects in this TDirectory as a dict of str → str.

Note that this does not read any data from the file.

iterkeys

ReadOnlyDirectory.iterkeys(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
Parameters:
  • recursive (bool) – If True, descend into any nested subdirectories. If False, only return the names of objects directly accessible in this TDirectory.

  • cycle (bool) – If True, include the cycle numbers in those names.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by name.

  • filter_classname (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

Returns the names of the objects in this TDirectory as an iterator over strings.

Note that this does not read any data from the file.

itervalues

ReadOnlyDirectory.itervalues(*, recursive=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
Parameters:
  • recursive (bool) – If True, descend into any nested subdirectories. If False, only return objects directly accessible in this TDirectory.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by name.

  • filter_classname (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

Returns objects in this TDirectory as an iterator over uproot.Model.

Note that this reads all objects that are selected by filter_name and filter_classname.

iteritems

ReadOnlyDirectory.iteritems(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
Parameters:
  • recursive (bool) – If True, descend into any nested subdirectories. If False, only return (name, object) pairs directly accessible in this TDirectory.

  • cycle (bool) – If True, include the cycle numbers in the names.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by name.

  • filter_classname (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

Returns (name, object) pairs for objects in this TDirectory as an iterator over 2-tuples of (str, uproot.Model).

Note that this reads all objects that are selected by filter_name and filter_classname.

iterclassnames

ReadOnlyDirectory.iterclassnames(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
Parameters:
  • recursive (bool) – If True, descend into any nested subdirectories. If False, only return the names and classnames of objects directly accessible in this TDirectory.

  • cycle (bool) – If True, include the cycle numbers in the names.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by name.

  • filter_classname (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

Returns the names and C++ (decoded) classnames of the objects in this TDirectory as an iterator of 2-tuples of (str, str).

Note that this does not read any data from the file.

descent_into_path

ReadOnlyDirectory.descent_into_path(where)

title_of

ReadOnlyDirectory.title_of(where, recursive=True)

Returns the title of the object selected by where.

The syntax for where is the same as in square brakets, namely that cycle numbers can be specified after semicolons (;) and nested TDirectories can be specified with slashes (/).

Unlike the square bracket syntax, this method cannot descend into the TBranches of a TTree.

Note that this does not read any data from the file.

classname_of

ReadOnlyDirectory.classname_of(where, encoded=False, version=None, recursive=True)

Returns the classname of the object selected by where. If encoded with a possible version, return a Python classname; otherwise, return a C++ (decoded) classname.

The syntax for where is the same as in square brakets, namely that cycle numbers can be specified after semicolons (;) and nested TDirectories can be specified with slashes (/).

Unlike the square bracket syntax, this method cannot descend into the TBranches of a TTree.

Note that this does not read any data from the file.

class_of

ReadOnlyDirectory.class_of(where, version=None, recursive=True)

Returns a class object for the ROOT object selected by where. If version is specified, get a uproot.model.VersionedModel; otherwise, get a uproot.model.DispatchByVersion or a versionless uproot.Model.

The syntax for where is the same as in square brakets, namely that cycle numbers can be specified after semicolons (;) and nested TDirectories can be specified with slashes (/).

Unlike the square bracket syntax, this method cannot descend into the TBranches of a TTree.

Note that this does not read any data from the file.

streamer_of

ReadOnlyDirectory.streamer_of(where, version='max', recursive=True)

Returns a TStreamerInfo (uproot.streamers.Model_TStreamerInfo) for the object selected by where and version.

The syntax for where is the same as in square brakets, namely that cycle numbers can be specified after semicolons (;) and nested TDirectories can be specified with slashes (/).

Unlike the square bracket syntax, this method cannot descend into the TBranches of a TTree.

Note that this does not read any data from the file.

key

ReadOnlyDirectory.key(where)

Returns a TKey (uproot.reading.ReadOnlyKey) for the object selected by where.

The syntax for where is the same as in square brakets, namely that cycle numbers can be specified after semicolons (;) and nested TDirectories can be specified with slashes (/).

Unlike the square bracket syntax, this method cannot descend into the TBranches of a TTree (since they have no TKeys).

Note that this does not read any data from the file.

fVersion

ReadOnlyDirectory.fVersion

Raw integer version of the TDirectory class.

fDatimeC

ReadOnlyDirectory.fDatimeC

Raw integer creation date/time.

created_on presents this time as a Python datetime.

fDatimeM

ReadOnlyDirectory.fDatimeM

Raw integer date/time of last modification.

modified_on presents this time as a Python datetime.

fNbytesKeys

ReadOnlyDirectory.fNbytesKeys

Number of bytes in the collection of TKeys (header key, number of directory keys, and directory keys).

fNbytesName

ReadOnlyDirectory.fNbytesName

Number of bytes in the header up to its title.

fSeekDir

ReadOnlyDirectory.fSeekDir

File seek position (int) of the TDirectory.

fSeekParent

ReadOnlyDirectory.fSeekParent

File seek position (int) of the parent object (TDirectory or TFile).

fSeekKeys

ReadOnlyDirectory.fSeekKeys

File seek position (int) to the collection of TKeys (header key, number of directory keys, and directory keys).

hook_before_read

ReadOnlyDirectory.hook_before_read(**kwargs)

Called in the uproot.ReadOnlyDirectory constructor before reading the TDirectory header fields.

This is the first hook called in the uproot.ReadOnlyDirectory constructor.

hook_before_interpret

ReadOnlyDirectory.hook_before_interpret(**kwargs)

Called in the uproot.ReadOnlyDirectory constructor after reading the TDirectory header fields and before interpreting them.

hook_before_read_keys

ReadOnlyDirectory.hook_before_read_keys(**kwargs)

Called in the uproot.ReadOnlyDirectory constructor after interpreting the TDirectory header fields and before reading the chunk of TKeys.

hook_before_header_key

ReadOnlyDirectory.hook_before_header_key(**kwargs)

Called in the uproot.ReadOnlyDirectory constructor after reading the chunk of TKeys and before interpreting the header TKey.

hook_before_keys

ReadOnlyDirectory.hook_before_keys(**kwargs)

Called in the uproot.ReadOnlyDirectory constructor after interpreting the header TKey and number of keys, and before interpeting the object TKeys.

hook_after_keys

ReadOnlyDirectory.hook_after_keys(**kwargs)

Called in the uproot.ReadOnlyDirectory constructor after interpeting the object TKeys.

This is the last hook called in the uproot.ReadOnlyDirectory constructor.