Clean up: small improvements (#120)

Small improvements - better error messages, improve the read me.

Author: gordonwatts

README.md

@@ -22,19 +22,17 @@ The selection string is often generated by another front-end library, for exampl
 Before you can use this library you'll need:
 
 - An environment based on python 3.6 or later
-- A `ServiceX` end-point. For example, `http://localhost:5000/servicex`, if `ServiceX` is running on a local `k8` cluster and the proper ports are open, or the public servicex instance (contact IRIS-HEP at xxx if you are part of the LHC to request an account, or with help setting up an instance).
+- A `ServiceX` end-point. This is usually gotten by logging into and getting approved at the servicex endpoint. Once you do that, you'll have an API token, which this library needs to access the `ServiceX` endpoint, and the web address where you got that token (the `endpoint` address).
 
 ### How to access your endpoint
 
-The `servicex` library searches for configuration information in several locations to determine what end-point it should connect to, in the following order:
+The API access information is normally placed in a `.servicex` file (to keep this confidential information form accidentally getting checked into a public repository). The `servicex` library searches for configuration information in several locations to determine what end-point it should connect to, in the following order:
 
 1. A `.servicex` file in the current working directory
 1. A `.servicex` file in the user's home directory (`$HOME` on Linux and Mac, and your profile
    directory on Windows).
 1. The `config_defaults.yaml` file distributed with the `servicex` package.
 
-If no endpoint is specified, then the library defaults to the developer endpoint, which is `http://localhost:5000` for the web-service API, and `localhost:9000` for the `minio` endpoint. No passwords are required.
-
 Create a `.servicex` file, in the `yaml` format, in the appropriate place for your work that contains the following:
 
 ```yaml
@@ -56,7 +54,7 @@ Finally, you can create the objects `ServiceXAdaptor` and `MinioAdaptor` by hand
 The following lines will return a `pandas.DataFrame` containing all the jet pT's from an ATLAS xAOD file containing Z->ee Monte Carlo:
 
 ```python
-    from servicex import ServiceX
+    from servicex import ServiceXDataset
     query = "(call ResultTTree (call Select (call SelectMany (call EventDataset (list 'localds:bogus')) (lambda (list e) (call (attr e 'Jets') 'AntiKt4EMTopoJets'))) (lambda (list j) (/ (call (attr j 'pt')) 1000.0))) (list 'JetPt') 'analysis' 'junk.root')"
     dataset = "mc15_13TeV:mc15_13TeV.361106.PowhegPythia8EvtGen_AZNLOCTEQ6L1_Zee.merge.DAOD_STDM3.e3601_s2576_s2132_r6630_r6264_p2363_tid05630052_00"
     ds = ServiceXDataset(dataset)
@@ -138,6 +136,10 @@ This code has been tested in several environments:
 - Python 3.6, 3.7, 3.8
 - Jupyter Notebooks (not automated), regular python command-line invoked source files
 
+### Non-standard backends
+
+When doing backend development, often ports 9000 and 5000 are forwarded to the local machine exposing the `minio` and `ServiceX_App` instances. In that case, you'll need to create a `.servicex` file that has `http://localhost:5000` as the end point. No API token is necessary if the development `ServiceX` instance doesn't have authorization turned on.
+
 ## API
 
 Everything is based around the `ServiceXDataset` object. Below is the documentation for the most common parameters.

servicex/servicex.py

@@ -270,8 +270,9 @@ async def _get_files(self, selection_query: str, data_type: str,
 
             except ServiceXUnknownRequestID as e:
                 self._cache.remove_query(query)
-                raise ServiceXException('ServiceX instance does not know about cached query '
-                                        f'{request_id}. Please resubmit.') from e
+                raise ServiceXException('Expected the ServiceX backend to know about query '
+                                        f'{request_id}. It did not. Cleared local cache. '
+                                        'Please resubmit to trigger a new query.') from e
 
             except ServiceXFatalTransformException as e:
                 transform_status = await self._servicex_adaptor.get_query_status(client,

servicex/servicex_config.py

@@ -132,7 +132,8 @@ def extract_info(ep) -> Tuple[str, Optional[str], Optional[str]]:
             seen_types = [str(ep['type'].as_str_expanded()) for ep in endpoints
                           if ep['type'].exists()]
             raise ServiceXException(f'Unable to find type {backend_type} '
-                                    f'in configuration. Saw: {", ".join(seen_types)}')
+                                    'in .servicex configuration file. Saw only types'
+                                    f': {", ".join(seen_types)}')
 
         # Nope - now we are going to have to just use the first one there.
         for ep in endpoints: