uproot.ReadOnlyFile

Defined in uproot.reading on line 470.

Inheritance order:

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