uproot.open

Defined in uproot.reading on line 23.

uproot.reading.open(path, *, object_cache=100, array_cache='100 MB', custom_classes=None, decompression_executor=None, interpretation_executor=None, **options)

Parameters:

• path (str or pathlib.Path) – The filesystem path or remote URL of the file to open. If a string, it may be followed by a colon (:) and an object path within the ROOT file, to return an object, rather than a file. Path objects are interpreted strictly as filesystem paths or URLs. Examples: "rel/file.root", "C:\abs\file.root", "http://where/what.root", "https://username:password@where/secure.root", "rel/file.root:tdirectory/ttree", Path("rel:/file.root"), Path("/abs/path:stuff.root")

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

Opens a ROOT file, possibly through a remote protocol.

If an object path is given, the return type of this function can be anything that can be extracted from a ROOT file (subclass of uproot.Model).

If an object path is not given, the return type is a uproot.ReadOnlyDirectory and not uproot.ReadOnlyFile. ROOT objects can be extracted from a uproot.ReadOnlyDirectory but not a uproot.ReadOnlyFile.

Options (type; default):

• file_handler (uproot.source.chunk.Source class; uproot.MemmapSource)

• xrootd_handler (uproot.source.chunk.Source class; uproot.XRootDSource)

• s3_handler (uproot.source.chunk.Source class; uproot.S3Source)

• http_handler (uproot.source.chunk.Source class; uproot.HTTPSource)

• object_handler (uproot.source.chunk.Source class; uproot.ObjectSource)

• 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)

Any object derived from a ROOT file is a context manager (works in Python’s with statement) that closes the file when exiting the with block. Therefore, the uproot.open function can and usually should be used in a with statement to clean up file handles and threads associated with open files:

with uproot.open("/path/to/file.root:path/to/histogram") as h:
    h.to_hist().plot()

# file is now closed, even if an exception was raised in the block

Other file entry points:

• uproot.open (this function): opens one file to read any of its objects.

• uproot.iterate: iterates through chunks of contiguous entries in TTrees.

• uproot.concatenate: returns a single concatenated array from TTrees.

• uproot.dask: returns an unevaluated Dask array from TTrees.

For remote ROOT files served over HTTP(S), basic authentication is supported. In this case, the credentials may be provided part of the URL in, as in https://username:password@example.org/secure/protected.root. Note that for security reasons, it is recommended basic authentication only be used for HTTPS resources.