[client] Deduplicate aggregation docstrings: shared time-window parameter block (~250 lines repeated) #184

Closed
opened 2026-10-27 11:31:56 +00:00 by mat · 0 comments
Owner

_aggregations.py repeats the same parameter documentation — measure_kind, aggregation_level, aggregation_type, time_ago_unit, time_ago_value, start, end, with their live-pinned enums — nearly verbatim across the 6 public methods (~250 of the file's 381 lines). Every enum re-pin (e.g. commits 12ccf49, 5c33dcf) has to touch all copies, which is exactly how docstring drift starts.

Fix options:

  • keep one canonical, fully-documented method (e.g. get_device_ts_time_ago) and have the others reference it ("See get_device_ts_time_ago for the shared time-window parameters"), documenting only what differs; or
  • extract the shared block to a module-level docstring section referenced from each method.

Either keeps help() useful while leaving a single place to update when an enum is re-pinned live.

Done when: the shared block exists in exactly one place; pytest -q green; no public signature change.

`_aggregations.py` repeats the same parameter documentation — `measure_kind`, `aggregation_level`, `aggregation_type`, `time_ago_unit`, `time_ago_value`, `start`, `end`, with their live-pinned enums — nearly verbatim across the 6 public methods (~250 of the file's 381 lines). Every enum re-pin (e.g. commits 12ccf49, 5c33dcf) has to touch all copies, which is exactly how docstring drift starts. **Fix options:** - keep one canonical, fully-documented method (e.g. `get_device_ts_time_ago`) and have the others reference it ("See `get_device_ts_time_ago` for the shared time-window parameters"), documenting only what differs; or - extract the shared block to a module-level docstring section referenced from each method. Either keeps `help()` useful while leaving a single place to update when an enum is re-pinned live. **Done when:** the shared block exists in exactly one place; `pytest -q` green; no public signature change.
mat closed this issue 2026-10-27 14:39:08 +00:00
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
mat/python-comwatt-client#184
No description provided.