Merge pull request #52 from prio-data/fix_message_return

improve readme and fix return of messages to client

README.md

@@ -168,9 +168,9 @@ Transforms are added to columns using the `transform` method
 
 Each transform method has a general transform type, e.g. `missing` followed by a specific function with brackets for arguments.
 
-A list of availble transforms can be obtained using the viewser CLI. A notebook giving examples of what each transform does can be found XXX.
+A list of available transforms can be obtained using the viewser CLI. A notebook giving examples of what each transform does can be found at https://github.com/prio-data/views3/tree/master/examples.
 
-Note that not all transforms are available at all levels of analysis. If a transform is reuested at an innapproprite loa, the queryset will be rejected by the server and an error message detailing which columns have requested incompatible transforms and loas will be returned.
+Note that not all transforms are available at all levels of analysis. If a transform is requested at an innapproprite loa, the queryset will be rejected by the server and an error message detailing which columns have requested incompatible transforms and loas will be returned.
 
 ## Publising a queryset
 
@@ -214,6 +214,31 @@ If errors are encountered during the database fetch or transform stages, an erro
 
 Note that priogrid-level dataframes, even compressed, can be large and can take significant time to download.
 
+## Common viewser error messages
+
+### Validation errors
+
+When a queryset is passed to the service, it is examined by a validation function which checks for easily-detected errors. Errors found by the validator will be received immediately by the client:
+
+'validation failed with illegal aggregation functions:   [list of bad aggregation functions]' - indicates that one or more non-existent aggregations was requested
+
+'validation failed with repeated column names:   [list of repeated column names]' - indicates that one or more column names has been used more than once in the queryset definition
+
+'validation failed with non-existent transforms:   [list of bad transforms]' - indicates that one or more non-existent transforms was requested
+
+'validation failed with disallowed transform loas: [list of bad transform:loa combinations] - indicates that the transform:loa pairings in the list are illegal
+
+### Runtime errors
+
+Other kinds of error are only detectable once processing the queryset has started, so these errors may take considerably longer to appear:
+
+'db fetch failed - missing columns: [list of bad column names]' - indicates that the listed columns do not exist in the VIEWS database
+
+'db fetch failed, to_loa = country_month, columns = ['/base/<bad_loa>.ged_sb_best_sum_nokgi/country_month.sum'], exception = no such loa is available right now!' - indicates that when trying to fetch the column 'ged_sb_best_sum_nokgi', the source loa <bad_loa> does not exist
+
+'transform failed,   file (path to transform function on server), line XX, in (transform), (specific error message)' - indicates that a transform operation failed, likely because of non-sensical parameters - the specific error message gives more details
+
+
 ## Funding
 
 The contents of this repository is the outcome of projects that have received funding from the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation programme (Grant agreement No. 694640, *ViEWS*) and Horizon Europe (Grant agreement No. 101055176, *ANTICIPATE*; and No. 101069312, *ViEWS* (ERC-2022-POC1)), Riksbankens Jubileumsfond (Grant agreement No. M21-0002, *Societies at Risk*), Uppsala University, Peace Research Institute Oslo, the United Nations Economic and Social Commission for Western Asia (*ViEWS-ESCWA*), the United Kingdom Foreign, Commonwealth & Development Office (GSRA – *Forecasting Fatalities in Armed Conflict*), the Swedish Research Council (*DEMSCORE*), the Swedish Foundation for Strategic Environmental Research (*MISTRA Geopolitics*), the Norwegian MFA (*Conflict Trends* QZA-18/0227), and the United Nations High Commissioner for Refugees (*the Sahel Predictive Analytics project*).

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "viewser"
-version = "6.0.2"
+version = "6.0.3"
 description = "The Views 3 CLI tool"
 authors = ["peder2911 <pglandsverk@gmail.com>"]
 readme = "README.md"

viewser/commands/queryset/operations.py

@@ -179,13 +179,13 @@ def _fetch(
                 print(f'{retries+1}: {message}', end="\r")
                 if 'failed' in message:
                     failed = True
-                    data = None
+                    data = message
 
             if retries > max_retries:
                 clear_output(wait=True)
                 print(f'Max attempts to retrieve exceeded ({max_retries}) : aborting retrieval', end="\r")
                 failed = True
-                data = None
+                data = message
 
             retries += 1