uproot.ReadOnlyFile
Defined in uproot.reading on line 470.
| Inheritance order: | 
|---|
- 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 - submitmethod) – The executor that is used to decompress- TBaskets; if None, a uproot.TrivialExecutor is created. Executors attached to a file are- shutdownwhen the file is closed.
- interpretation_executor (None or Executor with a - submitmethod) – The executor that is used to interpret uncompressed- TBasketdata as arrays; if None, a uproot.TrivialExecutor is created. Executors attached to a file are- shutdownwhen 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 - TFileheader 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 - withstatement, 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 - withstatement, 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 - MutableMappingcan 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 - MutableMappingcan 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 - TDirectoryof 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 - TStreamerInfosin the ROOT file.- A file’s - TStreamerInfosare only read the first time they are needed. Uproot has a suite of predefined models in- uproot.modelsto reduce the probability that- TStreamerInfoswill 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 - TStreamerInfoby 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) - classnameand- version.- The - versioncan 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) - classnameand- version.- The - classnameand- versionare 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.classespool.
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 - TBasketdata.- Executors attached to a file are - shutdownwhen 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 - TBasketdata.- Executors attached to a file are - shutdownwhen 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) - classnameand possible- version.- If the - versionis None, this function may return a uproot.model.DispatchByVersion.
- If the - versionis an integer,- "min"or- "max", then it returns a uproot.model.VersionedModel. Using- "min"or- "max"specifies the minium or maximum version- TStreamerInfodefined 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 - startup to- stopseek 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 - startup to- stop.
begin_chunk
- ReadOnlyFile.begin_chunk
- A special uproot.source.chunk.Chunk corresponding to the beginning of the file, from seek point - 0up 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 - TFileheader.
hook_after_interpret
- ReadOnlyFile.hook_after_interpret(**kwargs)
- Called in the uproot.ReadOnlyFile constructor after interpreting the - TFileheader 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
hook_before_read_decompress_streamers
hook_before_interpret_streamers
hook_after_interpret_streamers
file_path
Inherited from uproot.reading.CommonFileMethods.
- ReadOnlyFile.file_path
- The original path to the file (converted to - strif it was originally a- pathlib.Path).
options
Inherited from uproot.reading.CommonFileMethods.
- ReadOnlyFile.options
- The dict of - optionsoriginally passed to the file constructor.- If this is a uproot.WritableFile, the - optionsare 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 - TDirectorybeing 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 - TBrancheswithin 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 - TStreamerInfois always compressed with uproot.ZLIB, even if the compression is set to a different algorithm.- See fCompress. 
hex_uuid
Inherited from uproot.reading.CommonFileMethods.
uuid
Inherited from uproot.reading.CommonFileMethods.
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 - TFreedata, 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 - TFreedata, 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 - TFreedata, 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 - TBrancheswithin 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 - TStreamerInfois always compressed with uproot.ZLIB, even if the compression is set to a different algorithm.- See compression. 
fSeekInfo
Inherited from uproot.reading.CommonFileMethods.
fNbytesInfo
Inherited from uproot.reading.CommonFileMethods.
fUUID
Inherited from uproot.reading.CommonFileMethods.