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
submit
method) – The executor that is used to decompressTBaskets
; if None, a uproot.TrivialExecutor is created. Executors attached to a file areshutdown
when the file is closed.interpretation_executor (None or Executor with a
submit
method) – The executor that is used to interpret uncompressedTBasket
data as arrays; if None, a uproot.TrivialExecutor is created. Executors attached to a file areshutdown
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 fromTStreamerInfo
(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 (likeTTree
,TBranch
, andTDirectory
).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 inuproot.models
to reduce the probability thatTStreamerInfos
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
andversion
.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
andversion
.The
classname
andversion
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 returnstask(*args, **kwargs)
when itsFuture.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 returnstask(*args, **kwargs)
when itsFuture.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 possibleversion
.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 versionTStreamerInfo
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 tostop
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 tostop
.
begin_chunk
- ReadOnlyFile.begin_chunk
A special uproot.source.chunk.Chunk corresponding to the beginning of the file, from seek point
0
up tooptions["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 notb"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
str
if it was originally apathlib.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 aTTree
) 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.
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
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 aTTree
) 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.
fNbytesInfo
Inherited from uproot.reading.CommonFileMethods.
fUUID
Inherited from uproot.reading.CommonFileMethods.