uproot.ReadOnlyDirectory

Defined in uproot.reading on line 1284.

Inheritance order:
`collections.abc.Mapping` `collections.abc.Collection` `collections.abc.Sized` `collections.abc.Iterable` `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.

title_of

ReadOnlyDirectory.title_of(where)

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)

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)

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')

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.