diff --git a/astroquery/template_module/core.py b/astroquery/template_module/core.py index d752980ebc..0c336901fd 100644 --- a/astroquery/template_module/core.py +++ b/astroquery/template_module/core.py @@ -32,13 +32,29 @@ class DummyClass(BaseQuery): """ - Not all the methods below are necessary but these cover most of the common cases, new methods may be added if necessary, follow the guidelines at + Not all the methods below are necessary but these cover most of the common + cases, new methods may be added if necessary, follow the guidelines at + """ # use the Configuration Items imported from __init__.py to set the URL, TIMEOUT, etc. URL = conf.server TIMEOUT = conf.timeout - def query_object(self, object_name, get_query_payload=False, verbose=False): + # all query methods are implemented with an "async" method that handles + # making the actual HTTP request and returns the raw HTTP response, which + # should be parsed by a separate _parse_result method. The query_object + # method is created by async_to_sync automatically. It would look like + # this: + """ + def query_object(object_name, get_query_payload=False) + response = self.query_object_async(object_name, get_query_payload=get_query_payload) + if get_query_payload: + return response + result = self._parse_result(response, verbose=verbose) + return result + """ + + def query_object_async(self, object_name, get_query_payload=False): """ This method is for services that can parse object names. Otherwise use :meth:`astroquery.template_module.DummyClass.query_region`. @@ -59,52 +75,16 @@ def query_object(self, object_name, get_query_payload=False, verbose=False): Returns ------- - result : `~astropy.table.Table` - The result of the query as a `~astropy.table.Table` object. - All queries other than image queries should typically return - results like this. + response : `requests.Response` + The HTTP response returned from the service. + All async methods should return the raw HTTP response. Examples -------- While this section is optional you may put in some examples that show how to use the method. The examples are written similar to standard doctests in python. - """ - # typically query_object should have the following steps: - # 1. call the corresponding query_object_async method, and - # get the HTTP response of the query - # 2. check if 'get_query_payload' is set to True, then - # simply return the dict of HTTP request parameters. - # 3. otherwise call the parse_result method on the - # HTTP response returned by query_object_async and - # return the result parsed as astropy.Table - # These steps are filled in below, but may be replaced - # or modified as required. - - response = self.query_object_async(object_name, get_query_payload=get_query_payload) - if get_query_payload: - return response - result = self._parse_result(response, verbose=verbose) - return result - - # all query methods usually have a corresponding async method - # that handles making the actual HTTP request and returns the - # raw HTTP response, which should be parsed by a separate - # parse_result method. Since these async counterparts take in - # the same parameters as the corresponding query methods, but - # differ only in the return value, they should be decorated with - # prepend_docstr_noreturns which will automatically generate - # the common docs. See below for an example. - - @prepend_docstr_noreturns(query_object.__doc__) - def query_object_async(self, object_name, get_query_payload=False): - """ - Returns - ------- - response : `requests.Response` - The HTTP response returned from the service. - All async methods should return the raw HTTP response. """ # the async method should typically have the following steps: # 1. First construct the dictionary of the HTTP request params. @@ -132,14 +112,10 @@ def query_object_async(self, object_name, get_query_payload=False): if get_query_payload: return request_payload - # commons.send_request takes 4 parameters - the URL to query, the dict of - # HTTP request parameters we constructed above, the TIMEOUT which we imported - # from __init__.py and the type of HTTP request - either 'GET' or 'POST', which - # defaults to 'GET'. - response = commons.send_request(self.URL, - request_payload, - self.TIMEOUT, - request_type='GET') + # BaseQuery classes come with a _request method that includes a + # built-in caching system + response = self._request('GET', self.URL, params=request_payload, + timeout=self.TIMEOUT, cache=cache) return response # For services that can query coordinates, use the query_region method. @@ -149,7 +125,12 @@ def query_object_async(self, object_name, get_query_payload=False): # the keywords 'width' and 'height' should be used instead. The coordinates # may be accepted as an `astropy.coordinates` object or as a # string, which may be further parsed. - def query_region(self, coordinates, radius, width, height, get_query_payload=False, verbose=False): + + # similarly we write a query_region_async method that makes the + # actual HTTP request and returns the HTTP response + + def query_region_async(self, coordinates, radius, height, width, + get_query_payload=False, cache=True): """ Queries a region around the specified coordinates. @@ -168,27 +149,6 @@ def query_region(self, coordinates, radius, width, height, get_query_payload=Fal verbose : bool, optional Display VOTable warnings or not. - Returns - ------- - result : `~astropy.table.Table` - The result of the query as a `~astropy.table.Table` object. - All queries other than image queries should typically return - results like this. - """ - # the documentation and code are similar to the steps outlined in the - # `query_object` method, but a rough sketch is provided below - - response = self.query_region_async(coordinates, radius, height, width, - get_query_payload=get_query_payload) - result = self._parse_result(response, verbose=verbose) - return result - - # similarly we write a query_region_async method that makes the - # actual HTTP request and returns the HTTP response - - @prepend_docstr_noreturns(query_region.__doc__) - def query_region_async(self, coordinates, radius, height, width, get_query_payload=False): - """ Returns ------- response : `requests.Response` @@ -198,10 +158,8 @@ def query_region_async(self, coordinates, radius, height, width, get_query_paylo request_payload = self._args_to_payload(coordinates, radius, height, width) if get_query_payload: return request_payload - response = commons.send_request(self.URL, - request_payload, - self.TIMEOUT, - request_type='GET') + response = self._request('GET', self.URL, params=request_payload, + timeout=self.TIMEOUT, cache=cache) return response # as we mentioned earlier use various python regular expressions, etc @@ -233,7 +191,12 @@ def _parse_result(self, response, verbose=False): # return raw result/ handle in some way pass - # for image queries, the results should be returned as a + # Image queries do not use the async_to_sync approach: the "synchronous" + # version must be defined explicitly. The example below therefore presents + # a complete example of how to write your own synchronous query tools if + # you prefer to avoid the automatic approach. + # + # For image queries, the results should be returned as a # list of `astropy.fits.HDUList` objects. Typically image queries # have the following method family: # 1. get_images - this is the high level method that interacts with