From b8a1de7dbd013dd6e3991e08d9d9e50a678e4d99 Mon Sep 17 00:00:00 2001 From: Jon Stroop Date: Thu, 6 Mar 2025 21:17:40 -0500 Subject: [PATCH] docs cleanup following bad merge x --- README.md | 80 +++++++++++++++++++++++---------------------- TODO.md | 4 +++ docs/DEVELOPMENT.md | 26 +++++++-------- docs/STYLE.md | 6 ++-- 4 files changed, 61 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 2c04afa..da30351 100644 --- a/README.md +++ b/README.md @@ -94,58 +94,67 @@ client = FitbitClient( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", redirect_uri="YOUR_REGISTERED_REDIRECT_URI", - token_cache_path="/tmp/fb_tokens.json" # Optional: saves tokens between sessions - redirect_uri="YOUR_REGISTERED_REDIRECT_URI", - token_cache_path="/tmp/fb_tokens.json" # Optional: saves tokens between sessions + token_cache_path="/tmp/fb_tokens.json" ) # Will open browser and handle callback automatically client.authenticate() ``` -The `token_cache_path` parameter allows you to persist authentication tokens -between sessions. If provided, the client will: +You can also load your credentials from a JSON file, which is useful for keeping +secrets out of your code: -1. Load existing tokens from this file if available (avoiding re-authentication) +```python +from json import load +from fitbit_client import FitbitClient -2. Save new or refreshed tokens to this file automatically +# Load credentials from a JSON file +with open("secrets.json") as f: + secrets = load(f) -3. Handle token refresh when expired tokens are detected The `token_cache_path` - parameter allows you to persist authentication tokens between sessions. If - provided, the client will: +# Initialize Fitbit OAuth2 flow and get a client +client = FitbitClient(**secrets) -4. Load existing tokens from this file if available (avoiding re-authentication) +# Authenticate as usual +client.authenticate() +``` -5. Save new or refreshed tokens to this file automatically +Where secrets.json contains: -6. Handle token refresh when expired tokens are detected +```json +{ + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET", + "redirect_uri": "https://localhost:8080" +} +``` -## Setting Up Your Fitbit App +You can also include the optional token_cache_path: -1. Go to dev.fitbit.com and create a new application -2. Set OAuth 2.0 Application Type to "Personal" -3. Set Callback URL to "https://localhost:8080" (or your preferred local URL) -4. Set Callback URL to "https://localhost:8080" (or your preferred local URL) -5. Copy your Client ID and Client Secret +```json +{ + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET", + "redirect_uri": "https://localhost:8080", + "token_cache_path": "/tmp/tokens.json" +} +``` -## Additional Documentation +The `token_cache_path` parameter allows you to persist authentication tokens +between sessions. If provided, the client will: -### For API Library Users +1. Load existing tokens from this file if available (avoiding re-authentication) -- [LOGGING.md](docs/LOGGING.md): Understanding the dual-logger system -- [TYPES.md](docs/TYPES.md): JSON type system and method return types -- [NAMING.md](docs/NAMING.md): API method naming conventions -- [VALIDATIONS.md](docs/VALIDATIONS.md): Input parameter validation -- [ERROR_HANDLING.md](docs/ERROR_HANDLING.md): Exception hierarchy and handling +2. Save new or refreshed tokens to this file automatically -It's also worth reviewing -[Fitbit's Best Practices](https://dev.fitbit.com/build/reference/web-api/developer-guide/best-practices/) -for API usage. +3. Handle token refresh when expired tokens are detected -### Project Best Practices +## Setting Up Your Fitbit App -- [DEVELOPMENT.md](docs/DEVELOPMENT.md): Development environment and guidelines -- [STYLE.md](docs/STYLE.md): Code style and formatting standards +1. Go to dev.fitbit.com and create a new application +2. Set OAuth 2.0 Application Type to "Personal" +3. Set Callback URL to "https://localhost:8080" (or your preferred local URL) +4. Copy your Client ID and Client Secret ## Additional Documentation @@ -178,13 +187,6 @@ The methods are implemented in comments and should work, but I have not had a chance to verify them since this requires a publicly accessible server to receive webhook notifications. -If you're using this library with subscriptions and would like to help test and -implement this functionality, please open an issue or pull request! -[webhook subscriptions](https://dev.fitbit.com/build/reference/web-api/developer-guide/using-subscriptions/). -The methods are implemented in comments and should work, but I have not had a -chance to verify them since this requires a publicly accessible server to -receive webhook notifications. - If you're using this library with subscriptions and would like to help test and implement this functionality, please open an issue or pull request! diff --git a/TODO.md b/TODO.md index 0cff1f3..3b3bf9a 100644 --- a/TODO.md +++ b/TODO.md @@ -2,6 +2,10 @@ ## TODOs: +- be able to set scopes when initializing the client + +- security notes + - PyPi deployment - For all `create_...`methods, add the ID from the response to logs and maybe diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index e7e93a4..1e17077 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -77,19 +77,23 @@ fitbit-client/ │ │ ├── callback_handler.py │ │ ├── callback_server.py │ │ └── oauth.py -│ ├── client/ -│ │ ├── __init__.py -│ │ ├── fitbit_client.py -│ │ └── resource_methods_mixin.py +│ ├── client.py │ ├── resources/ │ │ ├── __init__.py │ │ ├── [resource files] │ │ └── constants.py +│ ├── utils/ +│ │ ├── __init__.py +│ │ ├── curl_debug_mixin.py +│ │ ├── date_validation.py +│ │ ├── helpers.py +│ │ ├── pagination_validation.py +│ │ └── types.py │ └── exceptions.py ├── tests/ │ ├── auth/ -│ ├── client/ -│ └── resources/ +│ ├── resources/ +│ └── utils/ └── [project files] ``` @@ -129,8 +133,8 @@ import typing import datetime ``` -The one excpetion to this rule is when an entire module needs to be `mock`ed for -testing, in which case, at least for the `json` package from the standare +The one exception to this rule is when an entire module needs to be `mock`ed for +testing, in which case, at least for the `json` package from the standard library, the entire package has to be imported. So `import json` is ok when that circumstance arises. @@ -378,10 +382,6 @@ The OAuth callback mechanism is implemented using two main classes: - Removing temporary certificate files - Clearing internal state -### Security Notes - -TODO - ## Git Workflow 1. Create a new branch for your feature/fix @@ -391,7 +391,7 @@ TODO ## Release Process -TODO +This section will be documented as we near our first release. ## Getting Help diff --git a/docs/STYLE.md b/docs/STYLE.md index 064967a..a751ea5 100644 --- a/docs/STYLE.md +++ b/docs/STYLE.md @@ -3,9 +3,9 @@ Linting and formatting are handled by [Black](https://github.com/psf/black), [isort](https://github.com/pycqa/isort/), [mdformat](https://github.com/pycqa/isort/), -[autoflake](https://github.com/PyCQA/autoflake) and a \[small script that adds a -path comment)[lint/add_file_headers.py]. That said, here are some general -guidelines: +[autoflake](https://github.com/PyCQA/autoflake) and a +[small script that adds a path comment](lint/add_file_headers.py). That said, +here are some general guidelines: ## Code Organization and Structure