sunpy/sunpy — pull request #1194 by Cadair (2014-10-20 13:23:33+00:00)
Title: Change JSOCClient API to match that of the Unified Downloader / VSO Client

This change makes the `JSOCClient` act like the VSO / Unified Downloader, in that you make a query that returns a list of results that you can then download.
To demonstrate this I copy some documentation below:

```python
Query JSOC for some HMI data at 45 second cadence:

>>> from sunpy.net import jsoc
>>> client = jsoc.JSOCClient()
>>> response = client.query(jsoc.Time('2010-01-01T00:00', '2010-01-01T01:00'),
... jsoc.Series('hmi.m_45s'))

the response object holds the records that your query will return:

>>> print response
DATE TELESCOP INSTRUME ... WAVELNTH WAVEUNIT
-------------------- -------- ---------- ... -------- ---------------
2012-09-05T08:27:19Z SDO/HMI HMI_FRONT2 ... 6173.0 Invalid KeyLink
2012-09-05T08:27:20Z SDO/HMI HMI_FRONT2 ... 6173.0 Invalid KeyLink

You can then make the request and download the data:

>>> res = client.get(response)
Request JSOC_20140724_947 was submitted 6 seconds ago, it is not ready to download.
Request JSOC_20140724_947 was exported at 2014.07.24_22:08:09_UT and is ready to download.
2 URLs found for Download. Totalling 30MB

This returns a Results instance which can be used to watch the progress
of the download.

>>> res.wait(progress=True)

*Example 2*

Query the JSOC for some AIA 171 data, and seperate out the staging and the
download steps:

>>> from sunpy.net import jsoc
>>> client = jsoc.JSOCClient()
>>> response = client.query(jsoc.Time('2014/1/1T00:00:00', '2014/1/1T00:00:36'),
jsoc.Series('aia.lev1_euv_12s'), jsoc.Segment('image'),
jsoc.Wave(171))

the response object holds the records that your query will return:

>>> print response
DATE TELESCOP INSTRUME T_OBS WAVELNTH WAVEUNIT
-------------------- -------- -------- ----------------------- -------- --------
2014-01-06T15:07:12Z SDO/AIA AIA_3 2013-12-31T23:59:36.34Z 171 angstrom
2014-01-06T15:07:12Z SDO/AIA AIA_3 2013-12-31T23:59:48.34Z 171 angstrom
2014-01-07T15:05:10Z SDO/AIA AIA_3 2014-01-01T00:00:00.34Z 171 angstrom
2014-01-07T15:05:10Z SDO/AIA AIA_3 2014-01-01T00:00:12.34Z 171 angstrom

You can then make the request:

>>> requestIDs = client.request_data(response)
[u'JSOC_20140724_952']

This returns a list of all the request identifiers for your query.

You can then check the status of the request, which will print out a status
message and return you the status code, a code of 1 means it is not ready
to download and a code of 0 means the request is staged and ready. A code
of 6 means an error, which is commonly that the request has not had time to
get into the que.

>>> status = client.check_request(requestIDs)
Request JSOC_20140724_955 was submitted 10 seconds ago, it is not ready to download.

Once the status code is 0 you can download the data using the `get_request`
method:

>>> res = client.get_request(requestIDs)

This returns a Results instance which can be used to watch the progress
of the download.

>>> res.wait(progress=True)
```