Skip to content

Commit a494f2f

Browse files
jpstroopjpstroop
committed
start naming and typing documentation
1 parent 3e12652 commit a494f2f

File tree

2 files changed

+259
-2
lines changed

2 files changed

+259
-2
lines changed

‎TODO.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
## TODO
44

5+
- [ ] Finish method naming and typing documentation.
6+
57
- [ ] Complete coverage
68

79
- [ ] Confront MyPy. See https://stackoverflow.com/a/51294709 for json help
@@ -10,13 +12,13 @@
1012
e.g. List[JSONType], Dict[str, JSONType], so that the user can actually know
1113
what to expect (or None, of course)
1214

13-
- [ ] add a note about typing, method naming semantics, aliases, and interns.
14-
1515
- [ ] Test that all methods have an alias in `Client` and that the signatures
1616
match
1717

1818
- [ ] Rationalize `ClientValidationException` subclass inheritance
1919

20+
- [ ] Set up CI!
21+
2022
- [ ] validate Calories From Fat:
2123
`fitbit_client.exceptions.ValidationException: Calories From Fat must be a valid non-negative number. Currently it is "146.79".`
2224
It needs to be a positive int!

‎docs/NAMING_AND_TYPING.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# Method Naming and Typing
2+
3+
The interns who developed the Fitbit
4+
[Web API](https://dev.fitbit.com/build/reference/web-api/) were not very
5+
consistent with naming of the API endpoints or the responses. Just a few
6+
examples:
7+
8+
- `create_activity_goals` allows you to create one goal at a time
9+
10+
- `add_favorite_foods` adds one food at a time, and "add" is only used here.
11+
It's "create" everywhere else.
12+
13+
- Method names that suggest they would return a list usually don't. They use the
14+
structure:
15+
16+
```json
17+
{
18+
"one-single-key": [
19+
"and then a list of objects/dicts here...."
20+
]
21+
}
22+
```
23+
24+
This would be a lovely and reliable convention! Except that:
25+
26+
- `get_favorite_activities`
27+
28+
- `get_frequent_activities`
29+
30+
- `get_recent_activity_types`
31+
32+
- `get_favorite_activities`
33+
34+
- `get_frequent_activities`
35+
36+
- `get_recent_activity_types`
37+
38+
- `get_devices`
39+
40+
- `get_food_locales`
41+
42+
- `get_food_units`
43+
44+
- `get_frequent_foods`
45+
46+
- `get_recent_foods`
47+
48+
- `get_spo2_summary_by_interval`
49+
50+
All return lists. If there is a rhyme or reason for this, I've not found it yet.
51+
52+
## Naming
53+
54+
Methods are named exactly as they appear in the
55+
[Web API Documentation](https://dev.fitbit.com/build/reference/web-api/). When
56+
there are inconsistencies (frequently) the documentation;s URL slug is the
57+
deciding factor. For example, for "Get AZM Time Series by Date"
58+
https://dev.fitbit.com/build/reference/web-api/active-zone-minutes-timeseries/get-azm-timeseries-by-date/,
59+
(which is it--"Time Series" or "timeseries"?) the method in our code will be
60+
`get_azm_timeseries_by_date()`.
61+
62+
TODO. Explain inconsistencies wrt plurals, aliases, lists vs object, etc.
63+
64+
## Typing
65+
66+
TODO. Explain the convention...
67+
68+
### Method Return Types
69+
70+
#### ActiveZoneMinutesResource
71+
72+
- `get_azm_timeseries_by_date -> Dict[str, JSONType]`
73+
- `get_azm_timeseries_by_interval -> Dict[str, JSONType]`
74+
75+
#### ActivityTimeSeriesResource
76+
77+
- `get_activity_timeseries_by_date -> Dict[str, JSONType]`
78+
- `get_activity_timeseries_by_date_range -> Dict[str, JSONType]`
79+
80+
#### ActivityResource
81+
82+
- `create_activity_goals -> Dict[str, JSONType]`
83+
- `create_activity_goal -> Dict[str, JSONType]` (alias for
84+
create_activity_goals)
85+
- `create_activity_log -> Dict[str, JSONType]`
86+
- `create_favorite_activity -> Dict[Never, Never]` ??
87+
- `delete_activity_log -> Dict[Never, Never]` ??
88+
- `delete_favorite_activity -> None`
89+
- `get_activity_goals -> Dict[str, JSONType]`
90+
- `get_daily_activity_summary -> Dict[str, JSONType]`
91+
- `get_activity_type -> Dict[str, JSONType]`
92+
- `get_all_activity_types -> Dict[str, JSONType]`
93+
- `get_favorite_activities -> List[JSONType]`
94+
- `get_frequent_activities -> List[JSONType]`
95+
- `get_recent_activity_types -> List[JSONType]`
96+
- `get_lifetime_stats -> Dict[str, JSONType]`
97+
- `get_activity_tcx -> str` (XML)
98+
- `get_activity_log_list -> Dict[str, JSONType]`
99+
100+
#### BaseResource
101+
102+
- `_make_request -> Any`
103+
104+
#### BodyTimeSeriesResource
105+
106+
- `get_body_timeseries_by_date -> Dict[str, JSONType]`
107+
- `get_body_timeseries_by_date_range -> Dict[str, JSONType]`
108+
- `get_bodyfat_timeseries_by_date -> Dict[str, JSONType]`
109+
- `get_bodyfat_timeseries_by_date_range -> Dict[str, JSONType]`
110+
- `get_weight_timeseries_by_date -> Dict[str, JSONType]`
111+
- `get_weight_timeseries_by_date_range -> Dict[str, JSONType]`
112+
113+
#### BodyResource
114+
115+
- `create_bodyfat_goal -> Dict[str, JSONType]`
116+
- `create_bodyfat_log -> Dict[str, JSONType]`
117+
- `create_weight_goal -> Dict[str, JSONType]`
118+
- `create_weight_log -> Dict[str, JSONType]`
119+
- `delete_bodyfat_log -> None`
120+
- `delete_weight_log -> None`
121+
- `get_body_goals -> Dict[str, JSONType]`
122+
- `get_bodyfat_log -> Dict[str, JSONType]`
123+
- `get_weight_logs -> Dict[str, JSONType]`
124+
125+
#### BreathingRateResource
126+
127+
- `get_breathing_rate_summary_by_date -> Dict[str, JSONType]`
128+
- `get_breathing_rate_summary_by_interval -> Dict[str, JSONType]`
129+
130+
#### CardioFitnessScoreResource
131+
132+
- `get_vo2_max_summary_by_date -> Dict[str, JSONType]`
133+
- `get_vo2_max_summary_by_interval -> Dict[str, JSONType]`
134+
135+
#### DeviceResource
136+
137+
- `get_devices -> List[JSONType]`
138+
- `create_alarm` (raises `NotImplementedError`)
139+
- `delete_alarm` (raises `NotImplementedError`)
140+
- `get_alarm` (raises `NotImplementedError`)
141+
- `update_alarm` (raises `NotImplementedError`)
142+
143+
#### ElectrocardiogramResource
144+
145+
- `get_ecg_log_list -> Dict[str, JSONType]`
146+
147+
#### FriendsResource
148+
149+
- `get_friends -> Dict[str, JSONType]`
150+
- `get_friends_leaderboard -> Dict[str, JSONType]`
151+
152+
#### HeartrateTimeSeriesResource
153+
154+
- `get_heartrate_timeseries_by_date -> Dict[str, JSONType]`
155+
- `get_heartrate_timeseries_by_date_range -> Dict[str, JSONType]`
156+
157+
#### HeartrateVariabilityResource
158+
159+
- `get_hrv_summary_by_date -> Dict[str, JSONType]`
160+
- `get_hrv_summary_by_interval -> Dict[str, JSONType]`
161+
162+
#### IntradayResource
163+
164+
- `get_azm_intraday_by_date -> Dict[str, JSONType]`
165+
- `get_azm_intraday_by_interval -> Dict[str, JSONType]`
166+
- `get_activity_intraday_by_date -> Dict[str, JSONType]`
167+
- `get_activity_intraday_by_interval -> Dict[str, JSONType]`
168+
- `get_breathing_rate_intraday_by_date -> Dict[str, JSONType]`
169+
- `get_breathing_rate_intraday_by_interval -> Dict[str, JSONType]`
170+
- `get_heartrate_intraday_by_date -> Dict[str, JSONType]`
171+
- `get_heartrate_intraday_by_interval -> Dict[str, JSONType]`
172+
- `get_hrv_intraday_by_date -> Dict[str, JSONType]`
173+
- `get_hrv_intraday_by_interval -> Dict[str, JSONType]`
174+
- `get_spo2_intraday_by_date -> Dict[str, JSONType]`
175+
- `get_spo2_intraday_by_interval -> Dict[str, JSONType]`
176+
177+
#### IrregularRhythmNotificationsResource
178+
179+
- `get_irn_alerts_list -> Dict[str, JSONType]`
180+
- `get_irn_profile -> Dict[str, JSONType]`
181+
182+
#### NutritionTimeSeriesResource
183+
184+
- `get_nutrition_timeseries_by_date -> Dict[str, JSONType]`
185+
- `get_nutrition_timeseries_by_date_range -> Dict[str, JSONType]`
186+
187+
#### NutritionResource
188+
189+
- `add_favorite_foods -> None`
190+
- `add_favorite_food -> None` (alias for add_favorite_foods)
191+
- `create_favorite_food -> None` (alias for add_favorite_foods)
192+
- `create_food -> Dict[str, JSONType]`
193+
- `create_food_log -> Dict[str, JSONType]`
194+
- `create_food_goal -> Dict[str, JSONType]`
195+
- `create_meal -> Dict[str, JSONType]`
196+
- `create_water_goal -> Dict[str, JSONType]`
197+
- `create_water_log -> Dict[str, JSONType]`
198+
- `delete_custom_food -> None`
199+
- `delete_favorite_foods -> None`
200+
- `delete_favorite_food -> None` (alias for delete_favorite_foods)
201+
- `delete_food_log -> None`
202+
- `delete_meal -> None`
203+
- `delete_water_log -> None`
204+
- `get_food -> Dict[str, JSONType]`
205+
- `get_food_goals -> Dict[str, JSONType]`
206+
- `get_food_log -> Dict[str, JSONType]`
207+
- `get_food_locales -> List[JSONType]`
208+
- `get_food_units -> List[JSONType]`
209+
- `get_frequent_foods -> List[JSONType]`
210+
- `get_recent_foods -> List[JSONType]`
211+
- `get_favorite_foods -> Dict[str, JSONType]`
212+
- `get_meal -> Dict[str, JSONType]`
213+
- `get_meals -> Dict[str, JSONType]`
214+
- `get_water_goal -> Dict[str, JSONType]`
215+
- `get_water_log -> Dict[str, JSONType]`
216+
- `search_foods -> Dict[str, JSONType]`
217+
- `update_food_log -> Dict[str, JSONType]`
218+
- `update_meal -> Dict[str, JSONType]`
219+
- `update_water_log -> Dict[str, JSONType]`
220+
221+
#### SleepResource
222+
223+
- `create_sleep_goals -> Dict[str, JSONType]`
224+
- `create_sleep_goal -> Dict[str, JSONType]` (alias for create_sleep_goals)
225+
- `create_sleep_log -> Dict[str, JSONType]`
226+
- `delete_sleep_log -> None`
227+
- `get_sleep_goals -> Dict[str, JSONType]`
228+
- `get_sleep_goal -> Dict[str, JSONType]` (alias for get_sleep_goals)
229+
- `get_sleep_log_by_date -> Dict[str, JSONType]`
230+
- `get_sleep_log_by_date_range -> Dict[str, JSONType]`
231+
- `get_sleep_log_list -> Dict[str, JSONType]`
232+
233+
#### SpO2Resource
234+
235+
- `get_spo2_summary_by_date -> Dict[str, JSONType]`
236+
- `get_spo2_summary_by_interval -> List[JSONType]`
237+
238+
#### SubscriptionResource
239+
240+
- `get_subscription_list -> Dict[str, JSONType]`
241+
- `create_subscription` (raises `NotImplementedError`)
242+
- `delete_subscription` (raises `NotImplementedError`)
243+
244+
#### TemperatureResource
245+
246+
- `get_temperature_core_summary_by_date -> Dict[str, JSONType]`
247+
- `get_temperature_core_summary_by_interval -> Dict[str, JSONType]`
248+
- `get_temperature_skin_summary_by_date -> Dict[str, JSONType]`
249+
- `get_temperature_skin_summary_by_interval -> Dict[str, JSONType]`
250+
251+
#### UserResource
252+
253+
- `get_profile -> Dict[str, JSONType]`
254+
- `update_profile -> Dict[str, JSONType]`
255+
- `get_badges -> Dict[str, JSONType]`

0 commit comments

Comments
 (0)