From 7f26fb27600b976ed78418513e036bc682d37eb6 Mon Sep 17 00:00:00 2001 From: Marcel Pinheiro Caraciolo Date: Fri, 29 Jul 2022 17:48:00 -0300 Subject: [PATCH] DOC: Added docummentation for release 0.5.2 --- docs/source/_version.txt | 2 +- .../reference/api/runpandas.StravaClient.rst | 84 ++++++++++ docs/source/reference/io.rst | 11 +- docs/source/user_guide/4-strava.ipynb | 157 ++++++++++++++++++ docs/source/user_guide/user_guide.rst | 3 +- docs/source/whatsnew/v0.5.2.txt | 23 +++ 6 files changed, 277 insertions(+), 3 deletions(-) create mode 100644 docs/source/reference/api/runpandas.StravaClient.rst create mode 100644 docs/source/user_guide/4-strava.ipynb create mode 100644 docs/source/whatsnew/v0.5.2.txt diff --git a/docs/source/_version.txt b/docs/source/_version.txt index 432fb37..24d31e6 100644 --- 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 new file mode 100644 index 0000000..cc761db --- /dev/null +++ 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 + + \ No newline at end of file diff --git a/docs/source/reference/io.rst b/docs/source/reference/io.rst index 7d46def..6d87e86 100644 --- 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 \ No newline at end of file + 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 new file mode 100644 index 0000000..50bc82a --- /dev/null +++ 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 \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 index c7982b4..4b21eca 100644 --- 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 \ No newline at end of file + 3-session + 4-strava \ No newline at end of file diff --git a/docs/source/whatsnew/v0.5.2.txt b/docs/source/whatsnew/v0.5.2.txt new file mode 100644 index 0000000..ce5d58e --- /dev/null +++ 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`) \ No newline at end of file