diff --git a/docs-sphinx/reading-options.rst b/docs-sphinx/reading-options.rst new file mode 100644 index 000000000..42ddc0d98 --- /dev/null +++ b/docs-sphinx/reading-options.rst @@ -0,0 +1,17 @@ +Options (type; default): + +* handler (:doc:`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 elements to be requested in a single vector + read, when using XRootD. +* 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 diff --git a/docs-sphinx/writing-options.rst b/docs-sphinx/writing-options.rst new file mode 100644 index 000000000..6b3570c63 --- /dev/null +++ b/docs-sphinx/writing-options.rst @@ -0,0 +1,14 @@ +Options (type; default): + +* initial_directory_bytes (int; 256): The number of bytes to allocate for new directories so that + TKeys can be added to them without needing immediate rewriting of the block. +* initial_streamers_bytes (int; 1024): The number of bytes to allocate for a new list of streamers + so that streamers can be added to it without needing immediate rewriting +* uuid_function (callable; ``uuid.uuid1``): Function to create the file's UUID and/or any directory's UUID. +* compression (:doc:`uproot.compression.Compression` or None; ``uproot.ZLIB(1)``): Compression algorithm + and level for new objects added to the file. Can be updated after creating + the :doc:`uproot.writing.writable.WritableFile`. + +See :doc:`uproot.writing.writable.WritableFile` for details on these options. + +Additional options are passed as ``storage_options`` to the fsspec filesystem diff --git a/src/uproot/_dask.py b/src/uproot/_dask.py index b217084a7..97fcd773a 100644 --- a/src/uproot/_dask.py +++ b/src/uproot/_dask.py @@ -184,17 +184,7 @@ def dask( * already-open TTree objects. * iterables of the above. - Options (type; default): - - * handler (:doc:`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) + ..include:: reading-options.rst Other file entry points: diff --git a/src/uproot/behaviors/TBranch.py b/src/uproot/behaviors/TBranch.py index 5900f41c6..4c7e528b0 100644 --- a/src/uproot/behaviors/TBranch.py +++ b/src/uproot/behaviors/TBranch.py @@ -165,17 +165,7 @@ def iterate( * already-open TTree objects. * iterables of the above. - Options (type; default): - - * handler (:doc:`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) + ..include:: reading-options.rst See also :ref:`uproot.behaviors.TBranch.HasBranches.iterate` to iterate within a single file. @@ -369,17 +359,7 @@ def concatenate( * already-open TTree objects. * iterables of the above. - Options (type; default): - - * handler (:doc:`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) + ..include:: reading-options.rst Other file entry points: diff --git a/src/uproot/reading.py b/src/uproot/reading.py index 334b69710..be4d957e7 100644 --- a/src/uproot/reading.py +++ b/src/uproot/reading.py @@ -79,17 +79,8 @@ def open( :doc:`uproot.reading.ReadOnlyDirectory` but not a :doc:`uproot.reading.ReadOnlyFile`. - Options (type; default): - - * handler (:doc:`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) + .. include:: reading-options.rst + 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. @@ -523,17 +514,7 @@ class ReadOnlyFile(CommonFileMethods): :doc:`uproot.reading.open` returns a :doc:`uproot.reading.ReadOnlyDirectory` and not a :doc:`uproot.reading.ReadOnlyFile`. - Options (type; default): - - * handler (:doc:`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) + .. include:: reading-options.rst See the `ROOT TFile documentation `__ for a specification of ``TFile`` header fields. diff --git a/src/uproot/writing/writable.py b/src/uproot/writing/writable.py index b99642cfe..c990fccaf 100644 --- a/src/uproot/writing/writable.py +++ b/src/uproot/writing/writable.py @@ -56,18 +56,7 @@ def create(file_path: str | Path | IO, **options): Returns a :doc:`uproot.writing.writable.WritableDirectory`. - Options (type; default): - - * initial_directory_bytes (int; 256) - * initial_streamers_bytes (int; 1024) - * uuid_function (callable; ``uuid.uuid1``) - * compression (:doc:`uproot.compression.Compression` or None): Compression algorithm - and level for new objects added to the file. Can be updated after creating - the :doc:`uproot.writing.writable.WritableFile`. Default is ``uproot.ZLIB(1)``. - - See :doc:`uproot.writing.writable.WritableFile` for details on these options. - - Additional options are passed to as ``storage_options`` to the fsspec filesystem + .. include:: writing-options.rst """ file_path = uproot._util.regularize_path(file_path) storage_options = { @@ -95,18 +84,7 @@ def recreate(file_path: str | Path | IO, **options): Returns a :doc:`uproot.writing.writable.WritableDirectory`. - Options (type; default): - - * initial_directory_bytes (int; 256) - * initial_streamers_bytes (int; 1024) - * uuid_function (callable; ``uuid.uuid1``) - * compression (:doc:`uproot.compression.Compression` or None): Compression algorithm - and level for new objects added to the file. Can be updated after creating - the :doc:`uproot.writing.writable.WritableFile`. Default is ``uproot.ZLIB(1)``. - - See :doc:`uproot.writing.writable.WritableFile` for details on these options. - - Additional options are passed to as ``storage_options`` to the fsspec filesystem. + .. include:: writing-options.rst """ file_path = uproot._util.regularize_path(file_path) @@ -154,14 +132,7 @@ def update(file_path: str | Path | IO, **options): Returns a :doc:`uproot.writing.writable.WritableDirectory`. - Options (type; default): - - * initial_directory_bytes (int; 256) - * uuid_function (callable; ``uuid.uuid1``) - - See :doc:`uproot.writing.writable.WritableFile` for details on these options. - - Additional options are passed to as ``storage_options`` to the fsspec filesystem + .. include:: writing-options.rst """ file_path = uproot._util.regularize_path(file_path)