uproot.ReadOnlyDirectory — Uproot documentation

# uproot.ReadOnlyDirectory

Defined in uproot.reading on line 1269.

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.

## 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.