uproot.ReadOnlyFile — Uproot documentation

# uproot.ReadOnlyFile

Defined in uproot.reading on line 470.

Inheritance order:
uproot.reading.CommonFileMethods

class uproot.reading.ReadOnlyFile(file_path: str | Path | IO, *, object_cache=100, array_cache='100 MB', custom_classes=None, decompression_executor=None, interpretation_executor=None, **options)
  Parameters:

    - file_path (str or `pathlib.Path`) – The filesystem path or remote URL of the file to open. Unlike uproot.open, it cannot be followed by a colon (`:`) and an object path within the ROOT file.

    - object_cache (None, MutableMapping, or int) – Cache of objects drawn from ROOT directories (e.g histograms, TTrees, other directories); if None, do not use a cache; if an int, create a new cache of this size.

    - array_cache (None, MutableMapping, or memory size) – Cache of arrays drawn from `TTrees`; if None, do not use a cache; if a memory size, create a new cache of this size.

    - custom_classes (None or MutableMapping) – If None, classes come from uproot.classes; otherwise, a container of class definitions that is both used to fill with new classes and search for dependencies.

    - decompression_executor (None or Executor with a `submit` method) – The executor that is used to decompress `TBaskets`; if None, a uproot.TrivialExecutor is created. Executors attached to a file are `shutdown` when the file is closed.

    - interpretation_executor (None or Executor with a `submit` method) – The executor that is used to interpret uncompressed `TBasket` data as arrays; if None, a uproot.TrivialExecutor is created. Executors attached to a file are `shutdown` when the file is closed.

    - options – See below.

  Handle to an open ROOT file, the way to access data in `TDirectories` (uproot.ReadOnlyDirectory) and create new classes from `TStreamerInfo` (streamers).

  All objects derived from ROOT files have a pointer back to the file, though this is a uproot.reading.DetachedFile (no active connection, cannot read more data) if the object’s classname is not in `uproot.reading.must_be_attached`: objects that can read more data and need to have an active connection (like `TTree`, `TBranch`, and `TDirectory`).

  Note that a uproot.ReadOnlyFile can’t be directly used to extract objects. To read data, use the uproot.ReadOnlyDirectory returned by root_directory. This is why uproot.open returns a uproot.ReadOnlyDirectory and not a uproot.ReadOnlyFile.

  Options (type; default):

  - handler (uproot.source.chunk.Source class; None)

  - timeout (float for HTTP, int for XRootD; 30)

  - max_num_elements (None or int; None)

  - num_workers (int; 1)

  - use_threads (bool; False on the emscripten platform (i.e. in a web browser), else True)

  - num_fallback_workers (int; 10)

  - begin_chunk_size (memory_size; 403, the smallest a ROOT file can be)

  - minimal_ttree_metadata (bool; True)

  See the ROOT TFile documentation for a specification of `TFile` header fields.

## detached

ReadOnlyFile.detached

  A uproot.reading.DetachedFile version of this file.

## close

ReadOnlyFile.close()

  Explicitly close the file.

  (Files can also be closed with the Python `with` statement, as context managers.)

  After closing, new objects and classes cannot be extracted from the file, but objects with uproot.reading.DetachedFile references instead of uproot.ReadOnlyFile that are still in the object_cache would still be accessible.

## closed

ReadOnlyFile.closed

  True if the file has been closed; False otherwise.

  The file may have been closed explicitly with close or implicitly in the Python `with` statement, as a context manager.

  After closing, new objects and classes cannot be extracted from the file, but objects with uproot.reading.DetachedFile references instead of uproot.ReadOnlyFile that are still in the object_cache would still be accessible.

## source

ReadOnlyFile.source

  The uproot.source.chunk.Source associated with this file, which is the “physical layer” that knows how to communicate with local file systems or through remote protocols like HTTP(S) or XRootD, but does not know what the bytes mean.

## object_cache

ReadOnlyFile.object_cache

  A cache used to hold previously extracted objects, so that code like

      h = my_file["histogram"]
      h = my_file["histogram"]
      h = my_file["histogram"]

  only reads the `"histogram"` once.

  Any Python `MutableMapping` can be used as a cache (i.e. a Python dict would be a cache that never evicts old objects), though uproot.LRUCache is a good choice because it is thread-safe and evicts least-recently used objects when a maximum number of objects is reached.

## array_cache

ReadOnlyFile.array_cache

  A cache used to hold previously extracted arrays, so that code like

      a = my_tree["branch"].array()
      a = my_tree["branch"].array()
      a = my_tree["branch"].array()

  only reads the `"branch"` once.

  Any Python `MutableMapping` can be used as a cache (i.e. a Python dict would be a cache that never evicts old objects), though uproot.LRUArrayCache is a good choice because it is thread-safe and evicts least-recently used objects when a size limit is reached.

## root_directory

ReadOnlyFile.root_directory

  The root `TDirectory` of the file (uproot.ReadOnlyDirectory).

## show_streamers

ReadOnlyFile.show_streamers(classname=None, version='max', stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)
  Parameters:

    - classname (None or str) – If None, all streamers that are defined in the file are shown; if a class name, only this class and its dependencies are shown.

    - version (int, "min", or "max") – Version number of the desired class; “min” or “max” returns the minimum or maximum version number, respectively.

    - stream (object with a `write(str)` method) – Stream to write the output to.

  Interactively display a file’s `TStreamerInfo`.

  Example with `classname="TLorentzVector"`:

      TVector3 (v3): TObject (v1)
          fX: double (TStreamerBasicType)
          fY: double (TStreamerBasicType)
          fZ: double (TStreamerBasicType)

      TObject (v1)
          fUniqueID: unsigned int (TStreamerBasicType)
          fBits: unsigned int (TStreamerBasicType)

      TLorentzVector (v4): TObject (v1)
          fP: TVector3 (TStreamerObject)
          fE: double (TStreamerBasicType)

## streamers

ReadOnlyFile.streamers

  A list of uproot.streamers.Model_TStreamerInfo objects representing the `TStreamerInfos` in the ROOT file.

  A file’s `TStreamerInfos` are only read the first time they are needed. Uproot has a suite of predefined models in `uproot.models` to reduce the probability that `TStreamerInfos` will need to be read (depending on the choice of classes or versions of the classes that are accessed).

  See also streamer_rules, which are read in the same pass with `TStreamerInfos`.

## streamer_rules

ReadOnlyFile.streamer_rules

  A list of strings of C++ code that help schema evolution of `TStreamerInfo` by providing rules to evaluate when new objects are accessed by old ROOT versions.

  Uproot does not evaluate these rules because they are written in C++ and Uproot does not have access to a C++ compiler.

  These rules are read in the same pass that produces streamers.

## streamers_named

ReadOnlyFile.streamers_named(classname)

  Returns a list of uproot.streamers.Model_TStreamerInfo objects that match C++ (decoded) `classname`.

  More that one streamer matching a given name is unlikely, but possible because there may be different versions of the same class. (Perhaps such files can be created by merging data from different ROOT versions with hadd?)

  See also streamer_named (singular).

## streamer_named

ReadOnlyFile.streamer_named(classname, version='max')

  Returns a single uproot.streamers.Model_TStreamerInfo object that matches C++ (decoded) `classname` and `version`.

  The `version` can be an integer or `"min"` or `"max"` for the minimum and maximum version numbers available in the file. The default is `"max"` because there’s usually only one.

  See also streamers_named (plural).

## streamer_dependencies

ReadOnlyFile.streamer_dependencies(classname, version='max')

  Returns a list of uproot.streamers.Model_TStreamerInfo objects that depend on the one that matches C++ (decoded) `classname` and `version`.

  The `classname` and `version` are interpreted the same way as streamer_named.

## custom_classes

ReadOnlyFile.custom_classes

  Either a dict of class objects specific to this file or None if it uses the common `uproot.classes` pool.

## decompression_executor

ReadOnlyFile.decompression_executor

  An object satisfying the Executor interface; `submit(task, *args, **kwargs)` returns a Future, which blocks and returns `task(*args, **kwargs)` when its `Future.result()` is called.

  This executor is used to decompress `TBasket` data.

  Executors attached to a file are `shutdown` when the file is closed.

## interpretation_executor

ReadOnlyFile.interpretation_executor

  An object satisfying the Executor interface; `submit(task, *args, **kwargs)` returns a Future, which blocks and returns `task(*args, **kwargs)` when its `Future.result()` is called.

  This executor is used to interpret arrays from uncompressed `TBasket` data.

  Executors attached to a file are `shutdown` when the file is closed.

## remove_class_definition

ReadOnlyFile.remove_class_definition(classname)

  Removes all versions of a class, specified by C++ (decoded) `classname`, from the custom_classes.

  If the file doesn’t have a custom_classes, this function adds one, so it does not remove the class from the common pool.

  If you want to remove a class from the common pool, you can do so with

      del uproot.classes[classname]

## class_named

ReadOnlyFile.class_named(classname, version=None)

  Returns or creates a class with a given C++ (decoded) `classname` and possible `version`.

  - If the `version` is None, this function may return a uproot.model.DispatchByVersion.

  - If the `version` is an integer, `"min"` or `"max"`, then it returns a uproot.model.VersionedModel. Using `"min"` or `"max"` specifies the minium or maximum version `TStreamerInfo` defined by the file; most files define only one so `"max"` is usually safe.

  If this file has custom_classes, the new class is added to that dict; otherwise, it is added to the global `uproot.classes`.

## chunk

ReadOnlyFile.chunk(start, stop)

  Returns a uproot.source.chunk.Chunk from the uproot.source.chunk.Source that is guaranteed to include bytes from `start` up to `stop` seek points in the file.

  If the desired range is satisfied by a previously saved chunk, such as begin_chunk, then that is returned. Hence, the returned chunk may include more data than the range from `start` up to `stop`.

## begin_chunk

ReadOnlyFile.begin_chunk

  A special uproot.source.chunk.Chunk corresponding to the beginning of the file, from seek point `0` up to `options["begin_chunk_size"]`.

## hook_before_create_source

ReadOnlyFile.hook_before_create_source(**kwargs)

  Called in the uproot.ReadOnlyFile constructor before the uproot.source.chunk.Source is created.

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

## hook_before_get_chunks

ReadOnlyFile.hook_before_get_chunks(**kwargs)

  Called in the uproot.ReadOnlyFile constructor after the uproot.source.chunk.Source is created but before attempting to get any uproot.source.chunk.Chunk, specifically the begin_chunk.

## hook_before_interpret

ReadOnlyFile.hook_before_interpret(**kwargs)

  Called in the uproot.ReadOnlyFile constructor after loading the begin_chunk and before interpreting its `TFile` header.

## hook_after_interpret

ReadOnlyFile.hook_after_interpret(**kwargs)

  Called in the uproot.ReadOnlyFile constructor after interpreting the `TFile` header and before raising an error if the first four bytes are not `b"root"`.

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

## hook_before_read_streamer_key

ReadOnlyFile.hook_before_read_streamer_key(**kwargs)

  Called in streamers before reading the `TKey` associated with the `TStreamerInfo`.

  This is the first hook called in streamers.

## hook_before_read_decompress_streamers

ReadOnlyFile.hook_before_read_decompress_streamers(**kwargs)

  Called in streamers after reading the `TKey` associated with the `TStreamerInfo` and before reading and decompressing the `TStreamerInfo` data.

## hook_before_interpret_streamers

ReadOnlyFile.hook_before_interpret_streamers(**kwargs)

  Called in streamers after reading and decompressing the `TStreamerInfo` data, but before interpreting it.

## hook_after_interpret_streamers

ReadOnlyFile.hook_after_interpret_streamers(**kwargs)

  Called in streamers after interpreting the `TStreamerInfo` data.

  This is the last hook called in streamers.

## file_path

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.file_path

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

## options

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.options

  The dict of `options` originally passed to the file constructor.

  If this is a uproot.WritableFile, the `options` are a copy of the current state of the options; change the properties (e.g. `initial_directory_bytes`, `uuid_function`) directly on the file object to make a lasting change. Modifying the copied dict does not change the file’s future behavior.

## root_version

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.root_version

  Version of ROOT used to write the file as a string.

  See root_version_tuple and fVersion.

## root_version_tuple

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.root_version_tuple

  Version of ROOT used to write teh file as a tuple.

  See root_version and fVersion.

## is_64bit

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.is_64bit

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

  A file that is larger than 4 GiB must be 64-bit ready, though any file might be. This refers to seek points like fSeekFree 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.

## compression

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.compression

  A uproot.compression.Compression object describing the compression setting for the ROOT file.

  Note that different objects (even different `TBranches` within a `TTree`) can be compressed differently, so this file-level compression is only a strong hint of how the objects are likely to be compressed.

  For some versions of ROOT `TStreamerInfo` is always compressed with uproot.ZLIB, even if the compression is set to a different algorithm.

  See fCompress.

## hex_uuid

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.hex_uuid

  The unique identifier (UUID) of the ROOT file expressed as a hexadecimal string.

  See uuid and fUUID.

## uuid

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.uuid

  The unique identifier (UUID) of the ROOT file expressed as a Python `uuid.UUID` object.

  See hex_uuid and fUUID.

## fVersion

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fVersion

  Raw version information for the ROOT file; this number is used to derive root_version, root_version_tuple, and is_64bit.

## fBEGIN

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fBEGIN

  The seek point (int) for the first data record, past the TFile header.

  Usually 100.

## fEND

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fEND

  The seek point (int) to the last free word at the end of the ROOT file.

## fSeekFree

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fSeekFree

  The seek point (int) to the `TFree` data, for managing empty spaces in a ROOT file (filesystem-like fragmentation).

## fNbytesFree

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fNbytesFree

  The number of bytes in the `TFree` data, for managing empty spaces in a ROOT file (filesystem-like fragmentation).

## nfree

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.nfree

  The number of objects in the `TFree` data, for managing empty spaces in a ROOT file (filesystem-like fragmentation).

## fNbytesName

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fNbytesName

  The number of bytes in the filename (`TNamed`) that is embedded in the ROOT file.

## fUnits

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fUnits

  Number of bytes in the serialization of file seek points, which can either be 4 or 8.

## fCompress

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fCompress

  The raw integer describing the compression setting for the ROOT file.

  Note that different objects (even different `TBranches` within a `TTree`) can be compressed differently, so this file-level compression is only a strong hint of how the objects are likely to be compressed.

  For some versions of ROOT `TStreamerInfo` is always compressed with uproot.ZLIB, even if the compression is set to a different algorithm.

  See compression.

## fSeekInfo

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fSeekInfo

  The seek point (int) to the `TStreamerInfo` data, where streamers are located.

## fNbytesInfo

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fNbytesInfo

  The number of bytes in the `TStreamerInfo` data, where streamers are located.

## fUUID

Inherited from uproot.reading.CommonFileMethods.

ReadOnlyFile.fUUID

  The unique identifier (UUID) of the ROOT file as a raw bytestring (Python `bytes`).

  See hex_uuid and uuid.