add download to get_values

Author: jnelson16

README.md

@@ -100,6 +100,8 @@ The __get_values__ function is the primary function for obtaining RegData from t
 * filtered (optional) - specify if poorly-performing industry results should be excluded. Default is True.
 * summary (optional) - specify if summary results should be returned, instead of document-level results. Default is True.
 * country (optional) - specify if all values for a country's jurisdiction ID should be returned. Default is False.
+* industryType (optional): Level of NAICS industries to include, default is '3-Digit'.
+* download (optional): If not False, a path location for a downloaded csv of the results.
 * verbose (optional) - value specifying how much debugging information should be printed for each function call. Higher number specifies more information, default is 0.
 
 In the example below, we are interested in the total number of restrictions and total number of words for the US (get_jurisdictions(38)) for the period 2010 to 2019.
@@ -168,5 +170,18 @@ agency_restrictions_ind = agency_by_industry.merge(
     agencies, by='agency_id')
 ```
 
+## Downloading Data
+
+There are two different ways to download data retrieved from RegCensusAPI:
+
+1. Use the pandas `df.to_csv(outpath)` function, which allows the user to download a csv of the data, with the given outpath. See the pandas [documentation][3] for more features.
+
+2. The __get_values__ function includes a `download` argument, which allows the user to simply download a csv of the data in the same line as the API call. See below for an example of this call.
+
+```
+rc.get_values(series = [1,2], jurisdiction = 38, date = [2010, 2019], download='regdata2010to2019.csv')
+```
+
 [1]:https://api.quantgov.org/swagger-ui.html
 [2]:https://www.quantgov.org/download-interactively
+[3]:https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_csv.html

regcensus/api.py

@@ -12,7 +12,8 @@
 
 def get_values(series, jurisdiction, date, filtered=True, summary=True,
                documentType=3, agency=None, industry=None, dateIsRange=True,
-               country=False, industryType='3-Digit', verbose=0):
+               country=False, industryType='3-Digit',
+               download=False, verbose=0):
     """
     Get values for a specific jurisdition and series
 
@@ -29,6 +30,10 @@ def get_values(series, jurisdiction, date, filtered=True, summary=True,
         dateIsRange (optional): Indicating whether the time parameter is range
             or should be treated as single data points
         country (optional): Get all values for country ID
+        industryType (optional): Level of NAICS industries to include,
+            default is '3-Digit'
+        download (optional): If not False, a path location for a
+            downloaded csv of the results
         verbose (optional): Print out the url of the API call
 
     Returns: pandas dataframe with the values and various metadata
@@ -131,6 +136,11 @@ def get_values(series, jurisdiction, date, filtered=True, summary=True,
     # Prints error message if call fails
     if (output.columns[:3] == ['title', 'status', 'detail']).all():
         print('WARNING:', output.iloc[0][-1])
+    elif download:
+        if type(download) == str:
+            clean_columns(output).to_csv(download, index=False)
+        else:
+            print("Valid outpath required to download.")
     # Returns clean data if no error
     else:
         return clean_columns(output)

tests/test_api.py

@@ -1,4 +1,5 @@
 import pytest
+import os
 import regcensus as rc
 
 
@@ -63,9 +64,11 @@ def test_get_values_multiple_series():
     assert order_results(results, 'seriesValue') == [405647.0, 35420432.0]
 
 
-def test_get_values_incorrect_series():
-    results = rc.get_values(series=None, jurisdiction=38, date=2019)
-    assert not results
+def test_get_values_incorrect_series(capsys):
+    rc.get_values(series=None, jurisdiction=38, date=2019)
+    assert capsys.readouterr().out == (
+        'Valid series ID required. Select from the following list:\n'
+    )
 
 
 def test_get_values_multiple_jurisdictions():
@@ -102,9 +105,9 @@ def test_get_values_one_industry():
     assert not results
 
 
-def test_get_values_incorrect_jurisdiction():
-    results = rc.get_values(series=1, jurisdiction=None, date=2019)
-    assert not results
+def test_get_values_incorrect_jurisdiction(capsys):
+    rc.get_values(series=1, jurisdiction=None, date=2019)
+    assert capsys.readouterr().out == 'Valid jurisdiction ID required.\n'
 
 
 def test_get_values_date_range():
@@ -124,9 +127,9 @@ def test_get_values_multiple_dates():
     ]
 
 
-def test_get_values_incorrect_dates():
-    results = rc.get_values(series=1, jurisdiction=38, date=None)
-    assert not results
+def test_get_values_incorrect_dates(capsys):
+    rc.get_values(series=1, jurisdiction=38, date=None)
+    assert capsys.readouterr().out == 'Valid date is required.\n'
 
 
 def test_get_values_country():
@@ -149,6 +152,21 @@ def test_get_values_multiple_agencies():
     assert order_results(results, 'seriesValue') == [34167.0, 91227.0]
 
 
+def test_get_values_download():
+    rc.get_values(
+        series=91, jurisdiction=38, date=2019, agency=195, download='test.csv'
+    )
+    assert os.path.exists('test.csv')
+    os.remove('test.csv')
+
+
+def test_get_values_incorrect_download(capsys):
+    rc.get_values(
+        series=91, jurisdiction=38, date=2019, agency=195, download=True
+    )
+    assert capsys.readouterr().out == 'Valid outpath required to download.\n'
+
+
 def test_list_document_types():
     results = rc.list_document_types()
     assert results['All Regulations'] == 3