Add docstrings to utils.py

Author: juanmcloaiza

astroquery/eso/core.py

@@ -31,7 +31,7 @@
 from ..exceptions import RemoteServiceError, NoResultsWarning, LoginError
 from ..query import QueryWithLogin
 from ..utils import schema
-from .utils import py2adql, _split_str_as_list_of_str, sanitize_val, to_cache, eso_hash
+from .utils import py2adql, _split_str_as_list_of_str, adql_sanitize_val, to_cache, eso_hash
 import pyvo
 
 __doctest_skip__ = ['EsoClass.*']
@@ -112,18 +112,22 @@ def timeout(self):
     # [W1203 - logging-fstring-interpolation]
     @staticmethod
     def log_info(message):
+        "Wrapper for logging function"
         log.info("%s", message)
 
     @staticmethod
     def log_warning(message):
+        "Wrapper for logging function"
         log.warning("%s", message)
 
     @staticmethod
     def log_error(message):
+        "Wrapper for logging function"
         log.error("%s", message)
 
     @staticmethod
     def log_debug(message):
+        "Wrapper for logging function"
         log.debug("%s", message)
 
     @timeout.setter
@@ -393,7 +397,7 @@ def _query_instrument_or_collection(self,
 
         # TODO
         # Check whether v is string or number, put in single quotes if string
-        where_constraints_strlist = [f"{k} = {sanitize_val(v)}" for k, v in filters.items()] + coord_constraint
+        where_constraints_strlist = [f"{k} = {adql_sanitize_val(v)}" for k, v in filters.items()] + coord_constraint
         where_constraints = [where_collections_str] + where_constraints_strlist
         query = py2adql(table=query_on.table_name, columns=columns, where_constraints=where_constraints,
                         top=self.ROW_LIMIT)
@@ -465,7 +469,7 @@ def query_main(self, *, column_filters=None, columns=None,
         columns = columns or []
         filters = {**dict(kwargs), **column_filters}
 
-        where_constraints_strlist = [f"{k} = {sanitize_val(v)}" for k, v in filters.items()]
+        where_constraints_strlist = [f"{k} = {adql_sanitize_val(v)}" for k, v in filters.items()]
         where_constraints = where_constraints_strlist
 
         if print_help:

astroquery/eso/utils.py

@@ -1,9 +1,15 @@
 #!/usr/bin/env/python
-from typing import Union, List
-import pickle
+
+"""
+utils.py: helper functions for the astropy.eso module
+"""
+
 import copy
-from astroquery import log
 import hashlib
+import pickle
+from typing import Union, List
+
+from astroquery import log
 
 
 def _split_str_as_list_of_str(column_str: str):
@@ -14,7 +20,10 @@ def _split_str_as_list_of_str(column_str: str):
     return column_list
 
 
-def sanitize_val(x):
+def adql_sanitize_val(x):
+    """
+    If the value is a string, put it into single quotes
+    """
     if isinstance(x, str):
         return f"'{x}'"
     else:
@@ -23,9 +32,13 @@ def sanitize_val(x):
 
 def py2adql(table: str, columns: Union[List, str] = None, where_constraints: List = None,
             order_by: str = '', order_by_desc=True, top: int = None):
+    """
+    Return the adql string corresponding to the parameters passed
+    """
     # Initialize / validate
     query_string = None
-    wc = [] if where_constraints is None else where_constraints[:]  # do not modify the original list
+    # do not modify the original list
+    wc = [] if where_constraints is None else where_constraints[:]
     if isinstance(columns, str):
         columns = _split_str_as_list_of_str(columns)
     if columns is None or len(columns) < 1:
@@ -50,12 +63,18 @@ def py2adql(table: str, columns: Union[List, str] = None, where_constraints: Lis
 
 
 def eso_hash(query_str: str, url: str):
+    """
+    Return a hash given an adql query string and an url.
+    """
     request_key = (query_str, url)
     h = hashlib.sha224(pickle.dumps(request_key)).hexdigest()
     return h
 
 
 def to_cache(table, cache_file):
+    """
+    Dump a table to a pickle file
+    """
     log.debug("Caching data to %s", cache_file)
 
     table = copy.deepcopy(table)