uproot.open — Uproot documentation

# uproot.open

Defined in uproot.reading on line 26.

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)

  - timeout (float for HTTP, int for XRootD; 30)

  - max_num_elements (None or int; None)

      The maximum number of elements to be requested in a single vector read, when using XRootD.

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