From 900990bb33274a324d05d678f3409ef5804d31a6 Mon Sep 17 00:00:00 2001 From: sapunyangkut <302607731+sapunyangkut@users.noreply.github.com> Date: Tue, 14 Jul 2026 06:26:26 +0800 Subject: [PATCH 1/2] docs: clarify max_num_elements behavior --- src/uproot/reading.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/uproot/reading.py b/src/uproot/reading.py index efcf623f3..a054dafdd 100644 --- a/src/uproot/reading.py +++ b/src/uproot/reading.py @@ -90,8 +90,10 @@ def open( 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 elements to be requested in a single vector - read, when using XRootD. + * 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 + entry-oriented functions such as :ref:`uproot.behaviors.TBranch.HasBranches.arrays`, ``iterate``, or + ``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. @@ -102,7 +104,6 @@ def open( * 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 :doc:`uproot.reading.open` function can and usually should From ed7849c902e14f6fe45282ace82420aa093f5404 Mon Sep 17 00:00:00 2001 From: sapunyangkut Date: Fri, 17 Jul 2026 01:44:34 +0800 Subject: [PATCH 2/2] docs: clarify max_num_elements across entry points Apply review feedback consistently to open, iterate, concatenate, dask, TTree, and RNTuple documentation. Developed and checked with OpenAI Codex assistance. --- src/uproot/_dask.py | 5 +++-- src/uproot/behaviors/RNTuple.py | 10 ++++++---- src/uproot/behaviors/TBranch.py | 10 ++++++---- src/uproot/reading.py | 8 ++++---- 4 files changed, 19 insertions(+), 14 deletions(-) diff --git a/src/uproot/_dask.py b/src/uproot/_dask.py index 8c4c2e3b2..1a628f563 100644 --- a/src/uproot/_dask.py +++ b/src/uproot/_dask.py @@ -195,8 +195,9 @@ def dask( 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 elements to be requested in a single vector - read, when using XRootD. + * 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. diff --git a/src/uproot/behaviors/RNTuple.py b/src/uproot/behaviors/RNTuple.py index 1d02765ed..03cf585e7 100644 --- a/src/uproot/behaviors/RNTuple.py +++ b/src/uproot/behaviors/RNTuple.py @@ -151,8 +151,9 @@ def iterate( 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 elements to be requested in a single vector - read, when using XRootD. + * 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. @@ -355,8 +356,9 @@ def concatenate( 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 elements to be requested in a single vector - read, when using XRootD. + * 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. diff --git a/src/uproot/behaviors/TBranch.py b/src/uproot/behaviors/TBranch.py index 92c63df0e..2ecfa74ab 100644 --- a/src/uproot/behaviors/TBranch.py +++ b/src/uproot/behaviors/TBranch.py @@ -176,8 +176,9 @@ def iterate( 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 elements to be requested in a single vector - read, when using XRootD. + * 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. @@ -391,8 +392,9 @@ def concatenate( 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 elements to be requested in a single vector - read, when using XRootD. + * 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. diff --git a/src/uproot/reading.py b/src/uproot/reading.py index a054dafdd..889651ddd 100644 --- a/src/uproot/reading.py +++ b/src/uproot/reading.py @@ -92,8 +92,7 @@ def open( 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 - entry-oriented functions such as :ref:`uproot.behaviors.TBranch.HasBranches.arrays`, ``iterate``, or - ``concatenate`` instead. + ``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. @@ -547,8 +546,9 @@ class ReadOnlyFile(CommonFileMethods): 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 elements to be requested in a single vector - read, when using XRootD. + * 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.