Merge pull request orcasgit#114 from orcasgit/docs

grokcode · web-flow · commit 8ecab2b69934 · 2017-01-24T15:17:04.000-08:00
Docs
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,3 +1,8 @@
+0.3.0 (2017-01-24)
+==================
+* Surface errors better
+* Use requests-oauthlib auto refresh to automatically refresh tokens if possible
+
 0.2.4 (2016-11-10)
 ==================
 * Call a hook if it exists when tokens are refreshed
diff --git a/docs/index.rst b/docs/index.rst
@@ -40,9 +40,90 @@ either ``None`` or a ``date`` or ``datetime`` object
 as ``%Y-%m-%d``.
 
 .. autoclass:: fitbit.Fitbit
-    :private-members:
     :members:
 
+    .. method:: body(date=None, user_id=None, data=None)
+
+       Get body data: https://dev.fitbit.com/docs/body/
+
+    .. method:: activities(date=None, user_id=None, data=None)
+
+       Get body data: https://dev.fitbit.com/docs/activity/
+
+    .. method:: foods_log(date=None, user_id=None, data=None)
+
+       Get food logs data: https://dev.fitbit.com/docs/food-logging/#get-food-logs
+
+    .. method:: foods_log_water(date=None, user_id=None, data=None)
+
+       Get water logs data: https://dev.fitbit.com/docs/food-logging/#get-water-logs
+
+    .. method:: sleep(date=None, user_id=None, data=None)
+
+       Get sleep data: https://dev.fitbit.com/docs/sleep/
+
+    .. method:: heart(date=None, user_id=None, data=None)
+
+       Get heart rate data: https://dev.fitbit.com/docs/heart-rate/
+
+    .. method:: bp(date=None, user_id=None, data=None)
+
+       Get blood pressure data: https://dev.fitbit.com/docs/heart-rate/
+
+    .. method:: delete_body(log_id)
+
+       Delete a body log, given a log id
+
+    .. method:: delete_activities(log_id)
+
+       Delete an activity log, given a log id
+
+    .. method:: delete_foods_log(log_id)
+
+       Delete a food log, given a log id
+
+    .. method:: delete_foods_log_water(log_id)
+
+       Delete a water log, given a log id
+
+    .. method:: delete_sleep(log_id)
+
+       Delete a sleep log, given a log id
+
+    .. method:: delete_heart(log_id)
+
+       Delete a heart log, given a log id
+
+    .. method:: delete_bp(log_id)
+
+       Delete a blood pressure log, given a log id
+
+    .. method:: recent_foods(user_id=None, qualifier='')
+
+       Get recently logged foods: https://dev.fitbit.com/docs/food-logging/#get-recent-foods
+
+    .. method:: frequent_foods(user_id=None, qualifier='')
+
+       Get frequently logged foods: https://dev.fitbit.com/docs/food-logging/#get-frequent-foods
+
+    .. method:: favorite_foods(user_id=None, qualifier='')
+
+       Get favorited foods: https://dev.fitbit.com/docs/food-logging/#get-favorite-foods
+
+    .. method:: recent_activities(user_id=None, qualifier='')
+
+       Get recently logged activities: https://dev.fitbit.com/docs/activity/#get-recent-activity-types
+
+    .. method:: frequent_activities(user_id=None, qualifier='')
+
+       Get frequently logged activities: https://dev.fitbit.com/docs/activity/#get-frequent-activities
+
+    .. method:: favorite_activities(user_id=None, qualifier='')
+
+       Get favorited foods: https://dev.fitbit.com/docs/activity/#get-favorite-activities
+
+
+
 Indices and tables
 ==================
 
diff --git a/fitbit/api.py b/fitbit/api.py
@@ -162,6 +162,27 @@ def refresh_token(self):
 
 
 class Fitbit(object):
+    """
+    Before using this class, create a Fitbit app
+    `here <https://dev.fitbit.com/apps/new>`_. There you will get the client id
+    and secret needed to instantiate this class. When first authorizing a user,
+    make sure to pass the `redirect_uri` keyword arg so fitbit will know where
+    to return to when the authorization is complete. See
+    `gather_keys_oauth2.py <https://github.com/orcasgit/python-fitbit/blob/master/gather_keys_oauth2.py>`_
+    for a reference implementation of the authorization process. You should
+    save ``access_token``, ``refresh_token``, and ``expires_at`` from the
+    returned token for each user you authorize.
+
+    When instantiating this class for use with an already authorized user, pass
+    in the ``access_token``, ``refresh_token``, and ``expires_at`` keyword
+    arguments. We also strongly recommend passing in a ``refresh_cb`` keyword
+    argument, which should be a function taking one argument: a token dict.
+    When that argument is present, we will automatically refresh the access
+    token when needed and call this function so that you can save the updated
+    token data. If you don't save the updated information, then you could end
+    up with invalid access and refresh tokens, and the only way to recover from
+    that is to reauthorize the user.
+    """
     US = 'en_US'
     METRIC = 'en_UK'
 
@@ -187,12 +208,23 @@ class Fitbit(object):
         'frequent',
     ]
 
-    def __init__(self, client_id, client_secret, system=US, **kwargs):
+    def __init__(self, client_id, client_secret, access_token=None,
+            refresh_token=None, expires_at=None, refresh_cb=None,
+            redirect_uri=None, system=US, **kwargs):
         """
         Fitbit(<id>, <secret>, access_token=<token>, refresh_token=<token>)
         """
         self.system = system
-        self.client = FitbitOauth2Client(client_id, client_secret, **kwargs)
+        self.client = FitbitOauth2Client(
+            client_id,
+            client_secret,
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_at=expires_at,
+            refresh_cb=refresh_cb,
+            redirect_uri=redirect_uri,
+            **kwargs
+        )
 
         # All of these use the same patterns, define the method for accessing
         # creating and deleting records once, and use curry to make individual
