This file provides guidance to agents when working with code in this repository.
Uproot is a library for reading and writing ROOT files (the CERN HEP data format) in pure Python and NumPy — an I/O library only, with no C++ ROOT dependency.
uv pip install -e . --group=dev # editable install with dev dependencies
uv run pytest tests # full test suite
uv run pytest tests/test_1603_num_entries.py # one test file
uv run pytest tests/test_1603_num_entries.py::test_name # one test
prek -a --quiet # lint/format (pre-commit: black, ruff, etc.)- Test files are named
test_<issue-or-PR-number>_<short_description>.py. New tests for a fix or feature go in a new file numbered after the issue/PR. - Tests pull sample ROOT files via
skhep_testdata; many tests need network access. Markers:slow,network,distributed,xrootd. - Pytest treats warnings as errors (
filterwarnings = error). - Codecov enforces 100% line and branch coverage, measured on the CPU job plus the GPU job (
tests-cuda/). Tests must not depend on the network or on timing to reach a line. Mark code that can't be reached with# pragma: no cover (reason)or# pragma: no branch (reason);raise AssertionErroris excluded inpyproject.toml. - Ruff lints
src/but nottests/; isort requiresfrom __future__ import annotationsin every module. Every source file starts with the license header line# BSD 3-Clause License; see https://github.com/scikit-hep/uproot/blob/main/LICENSE. - Version is derived from git tags via hatch-vcs (
src/uproot/version.pyis generated; don't edit).
The read path is layered: source → reading → model → behavior → interpretation.
-
Physical layer —
src/uproot/source/: gets raw bytes without interpreting them.Sourceimplementations for memory-mapped/plain files, HTTP, XRootD, fsspec, and Python file-like objects; data is delivered asChunks and navigated with aCursor(which tracks a byte position and does the low-level struct unpacking).src/uproot/sink/is the writable counterpart. -
File structure —
src/uproot/reading.py:uproot.openand the three classes that are not modeled like other ROOT objects:ReadOnlyFile(TFile),ReadOnlyDirectory(TDirectory), and TKey. Directories act as Mappings from object names to deserialized objects. -
Models —
src/uproot/model.pyandsrc/uproot/models/: every object read from a ROOT file is aModelsubclass. ROOT classes are versioned, soDispatchByVersionreads the version bytes and selects aVersionedModel(e.g.Model_TH1F_v3).src/uproot/models/holds hand-written/pre-generated models for common classes; for everything else, model classes are generated at runtime from the file's embeddedTStreamerInfo(streamers.py+deserialization.py) and placed in theuproot.dynamicmodule. C++ class names are encoded to Python identifiers viauproot.model.classname_encode(e.g.ROOT::RThing→Model_ROOT_3a3a_RThing).dev/make-models.pyregeneratesmodels/TH.pyandmodels/TGraph.py. -
Behaviors —
src/uproot/behaviors/: user-facing methods/properties mixed into models by naming convention, discovered byuproot.behavior.behavior_of: a submodule named after the encoded class name (without theModel_prefix) containing a class with the encoded name. E.g. histogram.values()/.to_hist()onTH1, and the main array-reading API (arrays,iterate,concatenate) onbehaviors/TBranch.py'sHasBranches. -
Interpretation —
src/uproot/interpretation/: turns raw TBasket bytes into arrays.identify.pypicks anInterpretation(numerical, jagged, strings, objects, grouped) for each branch;library.pymaps results to the output library (npNumPy,akAwkward — the default,pdPandas).containers.pyhandlesstd::vectoretc.;_awkwardforth.pygenerates AwkwardForth code to fast-path object-type branches.language/python.pyevaluates expressions passed toarrays().
- Writing —
src/uproot/writing/:uproot.create/recreate/update. Internals use a "cascade" design (_cascade.py,_cascadetree.py,_cascadentuple.py) where high-level writes cascade into updates of dependent file structures (freesegments, streamers, directories). - RNTuple (ROOT's TTree successor) is supported alongside TTree:
models/RNTuple.py,behaviors/RNTuple.py, and the writing cascade. - Dask/parallelism:
uproot.dasklives in_dask.py(+writing/_dask_write.py); thread-pool machinery insource/futures.py. tests-cuda/(GPU/kvikio) andtests-wasm/(Pyodide) have separate CI jobs and dependency groups (test-gpu-cu12/13,test-pyodide,test-xrootd).
Per CONTRIBUTING.md: significant AI assistance must be disclosed in the PR description, and PRs require meaningful human review — the human contributor remains the author.