deliver() documentation + some small fixes (#558)

Improve documentation of `deliver()` (and small doc tweaks)

docs/conf.py

@@ -9,12 +9,13 @@
 # import os, sys
 
 # sys.path.insert(0, os.path.abspath(".."))
+import servicex
 
 
 project = "ServiceX"
 copyright = "2024 Institute for Research and Innovation in Software for High Energy Physics (IRIS-HEP)"  # NOQA 501
 author = "Ben Galewsky, Gordon Watts, KyongEon Choi, Ketan Mahajan, Peter Onyisi"
-release = "3.0.0"
+release = servicex.__version__
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/examples.rst

@@ -1,5 +1,5 @@
 First Examples
-========
+=========
 Here are simple examples of how to use the ServiceX client to extract data from a dataset. Each
 examples shows the three ways to specify a request: as a YAML file, as a Python dictionary, and
 as a typed Python object.
@@ -117,6 +117,10 @@ The ``deliver`` function is used to submit a request to ServiceX. It takes a req
 three formats and returns a python dictionary with the name of the sample as a key
 and a list of URLs or local file paths as a value.
 
+Further documentation as to its use and arguments can be found in :py:func:`~servicex.deliver`.
+You can control which ServiceX instance to use, whether to use the local cache, how the progress bars are displayed,
+and more via arguments to this function.
+
 
 How to Use YAML Specification
 ------------------------------

docs/servicex.rst

@@ -1,14 +1,23 @@
 servicex package
 ================
 
+
+Module contents
+---------------
+
+.. automodule:: servicex
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
 Subpackages
 -----------
 
 .. toctree::
    :maxdepth: 4
 
    servicex.app
-   servicex.databinder
    servicex.func_adl
 
 Submodules
@@ -117,11 +126,3 @@ servicex.types module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: servicex
-   :members:
-   :undoc-members:
-   :show-inheritance:

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "servicex"
-version = "3.0.1-alpha.1"
+version = "3.1.1-alpha.1"
 description = "Python SDK and CLI Client for ServiceX"
 readme = "README.md"
 license = { text = "BSD-3-Clause" }  # SPDX short identifier

servicex/__init__.py

@@ -30,10 +30,13 @@
 from .models import ResultDestination
 import servicex.dataset as dataset
 import servicex.query as query
+import importlib.metadata
 
 OutputFormat = General.OutputFormatEnum
 Delivery = General.DeliveryEnum
 
+__version__ = importlib.metadata.version("servicex")
+
 __all__ = [
     "OutputFormat",
     "Delivery",
@@ -45,4 +48,5 @@
     "dataset",
     "query",
     "ProgressBarFormat",
+    "__version__",
 ]

servicex/servicex_client.py

@@ -53,9 +53,16 @@
 
 
 class ProgressBarFormat(str, Enum):
-    default = "default"
+    """Specify the way progress bars are displayed."""
+
+    expanded = "expanded"
+    """Show progress bars for each `Sample`"""
     compact = "compact"
+    """Show one overall summary set of progress bars"""
     none = "none"
+    """Show no progress bars at all"""
+    default = "expanded"
+    """Default (currently the same as "expanded")"""
 
 
 class ReturnValueException(Exception):
@@ -214,15 +221,38 @@ def _output_handler(
 
 
 def deliver(
-    config: Union[ServiceXSpec, Mapping[str, Any], str, Path],
+    spec: Union[ServiceXSpec, Mapping[str, Any], str, Path],
     config_path: Optional[str] = None,
     servicex_name: Optional[str] = None,
     return_exceptions: bool = True,
     fail_if_incomplete: bool = True,
     ignore_local_cache: bool = False,
     progress_bar: ProgressBarFormat = ProgressBarFormat.default,
 ):
-    config = _load_ServiceXSpec(config)
+    r"""
+    Execute a ServiceX query.
+
+    :param spec: The specification of the ServiceX query, either in a dictionary or a
+            :py:class:`~servicex.ServiceXSpec` object.
+    :param config_path: The filesystem path to search for the `servicex.yaml` or `.servicex` file.
+    :param servicex_name: The name of the ServiceX instance, as specified in the configuration
+            YAML file (None will give the default backend).
+    :param return_exceptions: If something goes wrong, bubble up the underlying exception for
+            debugging (as opposed to just having a generic error).
+    :param fail_if_incomplete: If :py:const:`True`: if not all input files are transformed, the
+            transformation will be marked as a failure and no outputs will be available. If
+            :py:const:`False`, a partial file list will be returned.
+    :param ignore_local_cache: If :py:const:`True`, ignore the local query cache and always run
+            the query on the remote ServiceX instance.
+    :param progress_bar: specify the kind of progress bar to show.
+            :py:const:`ProgressBarFormat.expanded` (the default) means every :py:class:`Sample`
+            will have its own progress bars; :py:const:`ProgressBarFormat.compact` gives one
+            summary progress bar for all transformations; :py:const:`ProgressBarFormat.none`
+            switches off progress bars completely.
+    :return: A dictionary mapping the name of each :py:class:`Sample` to a :py:class:`.GuardList`
+            with the file names or URLs for the outputs.
+    """
+    config = _load_ServiceXSpec(spec)
 
     if ignore_local_cache or config.General.IgnoreLocalCache:
         for sample in config.Sample:
@@ -232,7 +262,7 @@ def deliver(
 
     group = DatasetGroup(datasets)
 
-    if progress_bar == ProgressBarFormat.default:
+    if progress_bar == ProgressBarFormat.expanded:
         progress_options = {}
     elif progress_bar == ProgressBarFormat.compact:
         progress_options = {"overall_progress": True}
@@ -270,7 +300,7 @@ def __init__(self, backend=None, url=None, config_path=None):
         :param url: Direct URL of a serviceX deployment instead of using .servicex.
                     Can only work with hosts without auth, or the token is found
                     in a file pointed to by the environment variable BEARER_TOKEN_FILE
-        :param config_path: Optional path te the `.servicex` file. If not specified,
+        :param config_path: Optional path to the `.servicex` file. If not specified,
                     will search in local directory and up in enclosing directories
         """
         self.config = Configuration.read(config_path)

tests/test_databinder.py

@@ -932,6 +932,11 @@ def test_deliver_progress_options(transformed_result, codegen_list):
             config_path="tests/example_config.yaml",
             progress_bar=ProgressBarFormat.none,
         )
+        deliver(
+            spec,
+            config_path="tests/example_config.yaml",
+            progress_bar=ProgressBarFormat.expanded,
+        )
         with pytest.raises(ValueError):
             deliver(
                 spec,