Merge pull request #64 from corriporai/develop

DOCS: Documentation for release 0.5.2
corriporai · Jul 29, 2022 · 27c3793 · 27c3793
2 parents 3062d9c + 5a56c73
commit 27c3793
Show file tree

Hide file tree

Showing 7 changed files with 279 additions and 5 deletions.
diff --git a/docs/source/_version.txt b/docs/source/_version.txt
@@ -1 +1 @@
-Version: **0.5.0 (+4, 2938662)** Date: **July 20, 2021**
+Version: **0.5.1 (+38, b313d25)** Date: **July 29, 2022**
diff --git a/docs/source/reference/api/runpandas.StravaClient.rst b/docs/source/reference/api/runpandas.StravaClient.rst
@@ -0,0 +1,84 @@
+runpandas.StravaClient
+======================
+
+.. currentmodule:: runpandas
+
+.. autoclass:: StravaClient
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~StravaClient.__init__
+      ~StravaClient.authenticate_web
+      ~StravaClient.authorization_url
+      ~StravaClient.create_activity
+      ~StravaClient.create_subscription
+      ~StravaClient.deauthorize
+      ~StravaClient.delete_activity
+      ~StravaClient.delete_subscription
+      ~StravaClient.exchange_code_for_token
+      ~StravaClient.explore_segments
+      ~StravaClient.get_activities
+      ~StravaClient.get_activity
+      ~StravaClient.get_activity_comments
+      ~StravaClient.get_activity_kudos
+      ~StravaClient.get_activity_laps
+      ~StravaClient.get_activity_photos
+      ~StravaClient.get_activity_streams
+      ~StravaClient.get_activity_zones
+      ~StravaClient.get_athlete
+      ~StravaClient.get_athlete_clubs
+      ~StravaClient.get_athlete_followers
+      ~StravaClient.get_athlete_friends
+      ~StravaClient.get_athlete_koms
+      ~StravaClient.get_athlete_starred_segments
+      ~StravaClient.get_athlete_stats
+      ~StravaClient.get_both_following
+      ~StravaClient.get_club
+      ~StravaClient.get_club_activities
+      ~StravaClient.get_club_members
+      ~StravaClient.get_effort_streams
+      ~StravaClient.get_friend_activities
+      ~StravaClient.get_gear
+      ~StravaClient.get_related_activities
+      ~StravaClient.get_route
+      ~StravaClient.get_route_streams
+      ~StravaClient.get_routes
+      ~StravaClient.get_running_race
+      ~StravaClient.get_running_races
+      ~StravaClient.get_segment
+      ~StravaClient.get_segment_effort
+      ~StravaClient.get_segment_efforts
+      ~StravaClient.get_segment_leaderboard
+      ~StravaClient.get_segment_streams
+      ~StravaClient.get_starred_segments
+      ~StravaClient.get_token_from_file
+      ~StravaClient.handle_subscription_callback
+      ~StravaClient.handle_subscription_update
+      ~StravaClient.join_club
+      ~StravaClient.leave_club
+      ~StravaClient.list_subscriptions
+      ~StravaClient.refresh
+      ~StravaClient.refresh_access_token
+      ~StravaClient.save_token_to_file
+      ~StravaClient.set_token_from_dict
+      ~StravaClient.update_activity
+      ~StravaClient.update_athlete
+      ~StravaClient.upload_activity
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~StravaClient.access_token
+
+
diff --git a/docs/source/reference/io.rst b/docs/source/reference/io.rst
@@ -22,4 +22,13 @@ Social Apps
 
    read_strava
    read_nikerun
-   read_dir_nikerun
+   read_dir_nikerun
+
+
+Strava
+------
+
+.. autosummary::
+   :toctree: api/
+
+   StravaClient
diff --git a/docs/source/user_guide/4-strava.ipynb b/docs/source/user_guide/4-strava.ipynb
@@ -0,0 +1,157 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "d104368a",
+   "metadata": {},
+   "source": [
+    "# Loading your Strava running activities\n",
+    "\n",
+    "Many runners use third-party apps to track running activities. Runpandas supports loading activities directly from Strava Running Web App. In this notebook, we will extract this running data and analyse it locally using runpandas. We also take the opportunity to illustrate the runpandas methods for fetching and parsing data from Strava."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "f0ee1ef0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%load_ext autoreload\n",
+    "%autoreload 2\n",
+    "import warnings\n",
+    "warnings.filterwarnings('ignore')\n",
+    "\n",
+    "import runpandas\n",
+    "import os\n",
+    "import pandas as pd\n",
+    "pd.set_option('display.max_rows', 500)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e03adfbc",
+   "metadata": {},
+   "source": [
+    "We load the environment variables from our terminal or use a `.env` file with the STRAVA social app personal access tokens. You can create your own using the link instructions here: https://developers.strava.com/"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "360f8407",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from dotenv import load_dotenv\n",
+    "load_dotenv()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e287d2a0",
+   "metadata": {},
+   "source": [
+    "Firstly, import the runpandas ``StravaClient``, create a Client instance, and read in the client ID and secret loaded previously. Next the one time authentication. The command ``client.authenticate_web``  will open a browser with a URL for the athlete to use to approve access to their data from the app. \n",
+    "\n",
+    "The athlete is then prompted to log in to the Strava website and give consent to the requesting application. Once the user authorizes,  it will store the access token and refresh token. From this point this access token, which lasts for 6 hours, will be what you need to access data. The client also save it locally so it can be re-read and refreshed as needed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "346f6024",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client = runpandas.StravaClient()\n",
+    "client.authenticate_web()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "30d9c24e",
+   "metadata": {},
+   "source": [
+    "Now we can start to look at our athlete’s activities; at the example below we request the activity with the a specified id.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "32938533",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "Unable to set attribute media_type on entity <ActivityPhotoPrimary id=None>\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "Session                           Running: 18-06-2022 07:08:07\n",
+       "Total distance (meters)                                21389.8\n",
+       "Total ellapsed time                            0 days 02:02:20\n",
+       "Total moving time                              0 days 02:02:19\n",
+       "Average speed (km/h)                                       NaN\n",
+       "Average moving speed (km/h)                                NaN\n",
+       "Average pace (per 1 km)                                    NaN\n",
+       "Average pace moving (per 1 km)                             NaN\n",
+       "Average cadence                                        87.7889\n",
+       "Average moving cadence                                  87.847\n",
+       "Average heart rate                                     155.674\n",
+       "Average moving heart rate                              155.713\n",
+       "Average temperature                                        NaN\n",
+       "dtype: object"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "activity = runpandas.read_strava('7329257123')\n",
+    "activity.summary()"
+   ]
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "2a188acd0f27a53b17cfad69c436eac3f19ae51e9e26340e7d32ca2c8c278930"
+  },
+  "kernelspec": {
+   "display_name": "Python 3.8.3 ('runpandas_dev')",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/source/user_guide/user_guide.rst b/docs/source/user_guide/user_guide.rst
@@ -14,4 +14,5 @@ Further information on any specific method can be obtained in the
 
    1-overview
    2-heartrate
-   3-session
+   3-session
+   4-strava
diff --git a/docs/source/whatsnew/v0.5.2.txt b/docs/source/whatsnew/v0.5.2.txt
@@ -0,0 +1,23 @@
+.. _whatsnew_051:
+
+v0.5.2 (July 29, 2022)
+----------------------------
+
+This is a minor release from 0.5.1 and includes new features and improvements
+
+
+Highlights include:
+
+
+.. contents:: What's new in v0.5.2
+    :local:
+    :backlinks: none
+
+.. _whatsnew_052.enhancements:
+
+New features
+~~~~~~~~~~~~
+- Added StravaClient authentication handler for helping the authentication process (:pull:`55`)
+- Added docummentation with Strava Examples (:issue:`63`)
+- Fixed the test suites for Strava reading handlers and new tests for StravaClient helper class. (:issue:`63`)
+- improvements on linting and pre-commit process and remove Python 3.6 from the tests suite. (:issue:`59`)
diff --git a/runpandas/io/strava/_client.py b/runpandas/io/strava/_client.py
@@ -50,8 +50,7 @@ def log_message(self, *args):
 
 
 class StravaClient(Client):
-    """
-    The StravaClient object is a helper tool for handling
+    """The StravaClient object is a helper tool for handling
     the authentication process (i.e. authorization, token update, ...) against the Strava.
 
     Parameters
@@ -60,6 +59,7 @@ class StravaClient(Client):
         refresh_token: str, The Strava refresh token, optional
         client_secret: str, The strava client secret used for token refresh, optional
         client_id: int, The Strava client id used for token refresh, optional
+
     """
 
     def __init__(