stravaTUI
WIP
A TUI for viewing Strava run stats with a built-in race time prediction calculator
Requirements
- Python >= 3.10
- textual (latest)
- textual-plotext (latest)
- rich (latest)
- stravalib (latest)
Usage
Strava OAuth
The Strava data fetching is done using the Strava V3 API and requires OAuth authorisation in order to get an access token. To do this you first need to make a Strava application. The steps to do so can be found here. Once you’ve made a Strava application you’ll gain access to your Client ID and Client Secret. Next, you can clone the repo and make a copy of the .env file:
git clone https://github.com/aymenhafeez/stravaTUI
cd ...stravaTUI
WIP
A TUI for viewing Strava run stats with a built-in race time prediction calculator
Requirements
- Python >= 3.10
- textual (latest)
- textual-plotext (latest)
- rich (latest)
- stravalib (latest)
Usage
Strava OAuth
The Strava data fetching is done using the Strava V3 API and requires OAuth authorisation in order to get an access token. To do this you first need to make a Strava application. The steps to do so can be found here. Once you’ve made a Strava application you’ll gain access to your Client ID and Client Secret. Next, you can clone the repo and make a copy of the .env file:
git clone https://github.com/aymenhafeez/stravaTUI
cd stravaTUI
cp .env.example .env
Enter your Client ID and Client Secret into the .env file. Once you run the authentication script, it will read these in order to generate an access token and store the output in strava_token.json, which the app will read from to pull your Strava stats. To authenticate:
pip install -r requirements.txt
make run
and go to the authorisation link. You’ll be prompted to login to Strava and allow authorisation access. Once you click authorise you’ll see a json output. This will save to strava_token.json, so you can close the link and the authorisation script.
Once you’ve authorised, you can run the app:
python main.py
Development
Running the OAuth server
Setup as above or build and run as a containerised service with Docker:
make build
Alternatively, you can run the server directly with uvicorn:
pip install -r requirements.txt
uvicorn api:app --host 0.0.0.0 --port 5042 --reload --ws none
Running and type checking
python main.py
Run from the root stravatui directory:
mypy stravatui/
Project structure
stravatui/
├── main.py # Entry point
├── api.py # OAuth authorization server
├── Makefile # Build and run the OAuth server
├── Dockerfile # Build docker container image
├── docker-compose.yml # Docker orchestration configuration
└── stravatui/
├── activity_utils.py # Data processing helpers
├── app.py # UI and data loading
├── app.tcss # Styling
├── auth.py # Strava client initialisation
├── config.py # Theme setup
├── data_manager.py # Strava API data fetching
├── formatters.py # Data formatting helpers
├── race_calculator.py # Race time prediction calculator
├── ui/
│ ├── plot_data.py # Data processing for plots
│ ├── plot_setup.py # Plot setup and configuration
│ ├── tables.py # Data tables
│ └── text_labels.py # UI text components
└── data/ # Cached JSON data
Data caching
The data pulled from Strava is cached in stravatui/data to reduce continuous API calls every time the app runs.
activities.json # activity data from the last 60 days
all_time_run.json # all time run stats
ytd_run.json # year-to-date run stats
best_efforts.json # best effort data from the last 5 runs
The data gets purged if the app hasn’t been run in the last 24 hours to get up to date data.
Refresh token
The access token that gets granted on authorisation expires every six hours. When the app is run, a check is made to see if the access token is still valid, and if it isn’t, uses the corresponding refresh token to generate a new one. This way the authorisation script only needs to be run on initial installation (see stravatui/auth.py).
License
MIT License