Add pandas helper functions for get_stat_*

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "python.linting.enabled": true
+}

README.md

@@ -21,9 +21,9 @@ understanding API usage.
 For more detail on getting started with the API, please visit our
 [API Overview](http://docs.datacommons.org/api/).
 
-After you're ready to use the API, you can refer to `datacommons/examples` for
+When you are ready to use the API, you can refer to `datacommons/examples` for
 examples on how to use this package to perform various tasks. More tutorials and
-documentation can be found at [tutorials](https://datacommons.org/colab)!
+documentation can be found on our [tutorials page](https://datacommons.org/colab)!
 
 ## About Data Commons
 

datacommons/__init__.py

@@ -12,6 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+################################## IMPORTANT #################################
+# All user-facing functions in this package must be symlinked to the         #
+# datacommons_pandas pkg. This is so that users do not need to import both   #
+# libraries for pd support. Please keep the below imports in sync with the   #
+# __init__.py in the datacommons_pandas/ dir, and add a symlink when         #
+# creating a new file.                                                       #
+# TODO: https://github.com/datacommonsorg/api-python/issues/149              #
+##############################################################################
+
 # Data Commons SPARQL query support
 from datacommons.query import query
 
@@ -22,4 +31,4 @@
 from datacommons.stat_vars import get_stat_value, get_stat_series, get_stat_all
 
 # Other utilities
-from .utils import set_api_key
+from datacommons.utils import set_api_key

datacommons/examples/stat_vars.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Basic examples for StatisticalVariable-based param_set Commons API functions."""
+"""Basic examples for StatisticalVariable-based Data Commons API functions."""
 
 from __future__ import absolute_import
 from __future__ import division
@@ -25,16 +25,16 @@ def main():
     param_sets = [
         {
             'place': 'geoId/06085',
-            'stat_var': 'Count_Person',
+            'stat_var': "Count_Person",
         },
         {
             'place': 'geoId/06085',
-            'stat_var': 'Count_Person',
+            'stat_var': "Count_Person",
             'date': '2018',
         },
         {
             'place': 'geoId/06085',
-            'stat_var': 'Count_Person',
+            'stat_var': "Count_Person",
             'date': '2018',
             'measurement_method': 'CensusACS5yrSurvey',
         },
@@ -111,20 +111,20 @@ def call_str(pvs):
 
     pp = pprint.PrettyPrinter(indent=4)
     print(
-        "\nget_stat_all(['geoId/06085', 'country/FRA'], ['Median_Age_Person', 'Count_Person'])"
+        '\nget_stat_all(["geoId/06085", "country/FRA"], ["Median_Age_Person", "Count_Person"])'
     )
     print('>>> ')
     pp.pprint(
-        dc.get_stat_all(['geoId/06085', 'country/FRA'],
-                        ['Median_Age_Person', 'Count_Person']))
+        dc.get_stat_all(["geoId/06085", "country/FRA"],
+                        ["Median_Age_Person", "Count_Person"]))
 
     print(
-        "\nget_stat_all(['badPlaceId', 'country/FRA'], ['Median_Age_Person', 'Count_Person'])"
+        '\nget_stat_all(["badPlaceId", "country/FRA"], ["Median_Age_Person", "Count_Person"])'
     )
     print('>>> ')
     pp.pprint(
-        dc.get_stat_all(['badPlaceId', 'country/FRA'],
-                        ['Median_Age_Person', 'Count_Person']))
+        dc.get_stat_all(["badPlaceId", "country/FRA"],
+                        ["Median_Age_Person", "Count_Person"]))
 
 
 if __name__ == '__main__':

datacommons/stat_vars.py

@@ -20,13 +20,8 @@
 from __future__ import division
 from __future__ import print_function
 
-from datacommons.utils import _API_ROOT, _API_ENDPOINTS, _ENV_VAR_API_KEY
-
 import collections
-import json
-import os
-import six.moves.urllib.error
-import six.moves.urllib.request
+import six
 
 import datacommons.utils as utils
 
@@ -77,9 +72,9 @@ def get_stat_value(place,
         url += '&scaling_factor={}'.format(scaling_factor)
 
     try:
-      res_json = utils._send_request(url, post=False, use_payload=False)
+        res_json = utils._send_request(url, post=False, use_payload=False)
     except ValueError:
-      raise ValueError('No data in response.')
+        raise ValueError('No data in response.')
     return res_json['value']
 
 
@@ -102,7 +97,7 @@ def get_stat_series(place,
       scaling_factor (`int`): Optional, the preferred `scalingFactor` value.
     Returns:
       A `dict` mapping dates to value of `stat_var` for `place`,
-      filtered by optional args.
+      representing a time series that satisfies all input parameters.
 
     Raises:
       ValueError: If the payload returned by the Data Commons REST API is
@@ -148,55 +143,62 @@ def get_stat_all(places, stat_vars):
       >>> get_stat_all(["geoId/05", "geoId/06"], ["Count_Person", "Count_Person_Male"])
       {
         "geoId/05": {
-          "Count_Person": [
-            {
-              "val": {
-                "2010": 1633,
-                "2011": 1509,
-                "2012": 1581,
-              },
-              "observationPeriod": "P1Y",
-              "importName": "Wikidata",
-              "provenanceDomain": "wikidata.org"
-            },
-            {
-              "val": {
-                "2010": 1333,
-                "2011": 1309,
-                "2012": 131,
+          "Count_Person": {
+            "sourceSeries": [
+              {
+                "val": {
+                  "2010": 1633,
+                  "2011": 1509,
+                  "2012": 1581,
+                },
+                "observationPeriod": "P1Y",
+                "importName": "Wikidata",
+                "provenanceDomain": "wikidata.org"
               },
-              "observationPeriod": "P1Y",
-              "importName": "CensusPEPSurvey",
-              "provenanceDomain": "census.gov"
+              {
+                "val": {
+                  "2010": 1333,
+                  "2011": 1309,
+                  "2012": 131,
+                },
+                "observationPeriod": "P1Y",
+                "importName": "CensusPEPSurvey",
+                "provenanceDomain": "census.gov"
+              }
+            ],
             }
-          ],
-          "Count_Person_Male": [
-            {
-              "val": {
-                "2010": 1633,
-                "2011": 1509,
-                "2012": 1581,
-              },
-              "observationPeriod": "P1Y",
-              "importName": "CensusPEPSurvey",
-              "provenanceDomain": "census.gov"
-            }
-          ],
+          },
+          "Count_Person_Male": {
+            "sourceSeries": [
+              {
+                "val": {
+                  "2010": 1633,
+                  "2011": 1509,
+                  "2012": 1581,
+                },
+                "observationPeriod": "P1Y",
+                "importName": "CensusPEPSurvey",
+                "provenanceDomain": "census.gov"
+              }
+            ],
+          }
         },
         "geoId/02": {
-          "Count_Person": [],
-          "Count_Person_Male": [
-            {
-              "val": {
-                "2010": 13,
-                "2011": 13,
-                "2012": 322,
-              },
-              "observationPeriod": "P1Y",
-              "importName": "CensusPEPSurvey",
-              "provenanceDomain": "census.gov"
+          "Count_Person": {},
+          "Count_Person_Male": {
+              "sourceSeries": [
+                {
+                  "val": {
+                    "2010": 13,
+                    "2011": 13,
+                    "2012": 322,
+                  },
+                  "observationPeriod": "P1Y",
+                  "importName": "CensusPEPSurvey",
+                  "provenanceDomain": "census.gov"
+                }
+              ]
             }
-          ],
         }
       }
     """

datacommons/test/core_test.py

@@ -311,7 +311,7 @@ def read(self):
       return MockResponse(json.dumps({'payload': res_json}))
 
   # Otherwise, return an empty response and a 404.
-  return urllib.error.HTTPError
+  return urllib.error.HTTPError(None, 404, None, None, None)
 
 
 class TestGetPropertyLabels(unittest.TestCase):

datacommons/test/places_test.py

@@ -212,7 +212,7 @@ def read(self):
     return MockResponse(json.dumps({'payload': res_json}))
 
   # Otherwise, return an empty response and a 404.
-  return urllib.error.HTTPError
+  return urllib.error.HTTPError(None, 404, None, None, None)
 
 class TestGetPlacesIn(unittest.TestCase):
   """ Unit stests for get_places_in. """