Reorder and update metadata docstring, convert last_update field to datetime

Python-packages/covidcast-py/covidcast/covidcast.py

@@ -1,8 +1,8 @@
 """This is the client side library for accessing the COVIDcast API."""
 import warnings
 from datetime import timedelta, date
-from typing import Union, Iterable, Tuple, List
 from functools import reduce
+from typing import Union, Iterable, Tuple, List
 
 import pandas as pd
 from delphi_epidata import Epidata
@@ -213,21 +213,21 @@ def metadata() -> pd.DataFrame:
       ``signal``
         Signal name.
 
-      ``min_time``
-        First day for which this signal is available.
-
-      ``max_time``
-        Most recent day for which this signal is available.
+      ``time_type``
+        Temporal resolution at which this signal is reported. "day", for
+        example, means the signal is reported daily.
 
       ``geo_type``
         Geographic level for which this signal is available, such as county,
         state, msa, or hrr. Most signals are available at multiple geographic
         levels and will hence be listed in multiple rows with their own
         metadata.
 
-      ``time_type``
-        Temporal resolution at which this signal is reported. "day", for
-        example, means the signal is reported daily.
+      ``min_time``
+        First day for which this signal is available.
+
+      ``max_time``
+        Most recent day for which this signal is available.
 
       ``num_locations``
         Number of distinct geographic locations available for this signal. For
@@ -246,6 +246,17 @@ def metadata() -> pd.DataFrame:
       ``stdev_value``
         The sample standard deviation of all reported values.
 
+      ``last_update``
+        The UTC datetime for when the signal value was last updated.
+
+      ``max_issue``
+        Most recent date data was issued.
+
+      ``min_lag``
+        Smallest lag from observation to issue, in days.
+
+      ``max_lag``
+        Largest lag from observation to issue, in days.
     """
     meta = Epidata.covidcast_meta()
 
@@ -257,7 +268,7 @@ def metadata() -> pd.DataFrame:
     meta_df = pd.DataFrame.from_dict(meta["epidata"])
     meta_df["min_time"] = pd.to_datetime(meta_df["min_time"], format="%Y%m%d")
     meta_df["max_time"] = pd.to_datetime(meta_df["max_time"], format="%Y%m%d")
-
+    meta_df["last_update"] = pd.to_datetime(meta_df["last_update"], unit="s")
     return meta_df
 
 

Python-packages/covidcast-py/tests/covidcast/test_covidcast.py

@@ -77,19 +77,21 @@ def test_signal(mock_covidcast, mock_metadata):
 @patch("delphi_epidata.Epidata.covidcast_meta")
 def test_metadata(mock_covidcast_meta):
     # not generating full DF since most attributes used
-    mock_covidcast_meta.side_effect = [{"result": 1,  # successful API response
-                                        "epidata": [{"max_time": 20200622, "min_time": 20200421},
-                                                    {"max_time": 20200724, "min_time": 20200512}],
-                                        "message": "success"},
-                                       {"result": 0,  # unsuccessful API response
-                                        "epidata": [{"max_time": 20200622, "min_time": 20200421},
-                                                    {"max_time": 20200724, "min_time": 20200512}],
-                                        "message": "error: failed"}]
-
+    mock_covidcast_meta.side_effect = [
+        {"result": 1,  # successful API response
+         "epidata": [{"max_time": 20200622, "min_time": 20200421, "last_update": 12345},
+                     {"max_time": 20200724, "min_time": 20200512, "last_update": 99999}],
+         "message": "success"},
+        {"result": 0,  # unsuccessful API response
+         "epidata": [{"max_time": 20200622, "min_time": 20200421},
+                     {"max_time": 20200724, "min_time": 20200512}],
+         "message": "error: failed"}]
     # test happy path
     response = covidcast.metadata()
-    expected = pd.DataFrame({"max_time": [datetime(2020, 6, 22), datetime(2020, 7, 24)],
-                             "min_time": [datetime(2020, 4, 21), datetime(2020, 5, 12)]})
+    expected = pd.DataFrame({
+        "max_time": [datetime(2020, 6, 22), datetime(2020, 7, 24)],
+        "min_time": [datetime(2020, 4, 21), datetime(2020, 5, 12)],
+        "last_update": [datetime(1970, 1, 1, 3, 25, 45), datetime(1970, 1, 2, 3, 46, 39)]})
     assert sort_df(response).equals(sort_df(expected))
 
     # test failed response raises RuntimeError