add descriptions of some options in uproot.open

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

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

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:
 

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:
 

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 <https://root.cern.ch/doc/master/classTFile.html>`__
     for a specification of ``TFile`` header fields.

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)