uproot.open

Defined in uproot.reading on line 27.

uproot.reading.open(path: str | Path | IO | dict[str | Path | IO, str], *, 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):

  • handler (uproot.source.chunk.Source class; None): Class implementing reading from the data source. If None, deduced from input file type.

  • timeout (float for HTTP, int for XRootD; default defined by source implementation): The time in seconds to wait before giving up on the connection. Ignored for non-internet sources like local file paths.

  • max_num_elements (None or int; None): The maximum number of byte ranges requested in a single XRootD vector read. This does not limit the number of TTree or RNTuple entries read; pass entry_stop to arrays, uproot.iterate, or uproot.concatenate instead.

  • num_workers (int; 1): Number of tasks to spawn for reading, only used by some source types

  • use_threads (bool; False on the emscripten platform (i.e. in a web browser), else True): Use multi-threading when spawning workers.

  • num_fallback_workers (int; 10): Number of tasks to spawn for reading in fallback mode (for example, multi-threading requests instead of a multipart GET for an http source)

  • begin_chunk_size (memory_size; 403, the smallest a ROOT file can be): Size of first chunk that we attempt to read in bytes.

  • minimal_ttree_metadata (bool; True): Skip rarely used metadata and defer reading of embedded TBaskets

  • http_max_header_bytes (int; 21784): Maximum size of HTTP packet in bytes when the source is http

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.