📝 docs: dedupe aggregation time-window docstrings, fix type drift and time_ago_value default #203

Merged
mat merged 1 commit from docs/agg-docstring-overhaul into main 2026-10-27 14:39:08 +00:00
Owner

Summary

The six aggregation methods carried ~250 lines of near-verbatim time-window docstrings — every enum re-pin had to touch all copies (#184). Now one canonical holder + references, plus the type-drift sweep (#188) and the default alignment (#186):

get_device_ts_time_ago      ──► canonical: full docs + live-pinned enums
  └── 5 satellites           ──► "see get_device_ts_time_ago, the canonical holder..."
      (per-method default deltas noted inline, e.g. aggregation_level="DAY")

time_ago_value default       ──► int 1 everywhere ("1" str in get_device_ts_time_ago; wire unchanged — params are str()-ified)
type drift                   ──► site_id/device_id/capacity_id/connected_object_id documented (int | str) everywhere
README                       ──► time_ago_value = 1

Evidence

  • Before: 6 copies of the measure_kind/aggregation_level/aggregation_type/time_ago enums; 15 docstring spots documenting (str) against int | str signatures.
    After: enums live in exactly one place; grep "(str)" against signatures comes back clean; pytest -q → 242 passed with zero test edits (the wire format is unchanged — timeAgoValue is str()-ed in _aggregations_query), mypy → clean.

Merge Danger

Door: two-way

Blast Radius: none — docstrings + a cosmetic default change with identical wire format.

Closes #184. Closes #186. Closes #188.

## Summary The six aggregation methods carried ~250 lines of near-verbatim time-window docstrings — every enum re-pin had to touch all copies (#184). Now one canonical holder + references, plus the type-drift sweep (#188) and the default alignment (#186): ```text get_device_ts_time_ago ──► canonical: full docs + live-pinned enums └── 5 satellites ──► "see get_device_ts_time_ago, the canonical holder..." (per-method default deltas noted inline, e.g. aggregation_level="DAY") time_ago_value default ──► int 1 everywhere ("1" str in get_device_ts_time_ago; wire unchanged — params are str()-ified) type drift ──► site_id/device_id/capacity_id/connected_object_id documented (int | str) everywhere README ──► time_ago_value = 1 ``` ## Evidence - **Before:** 6 copies of the measure_kind/aggregation_level/aggregation_type/time_ago enums; 15 docstring spots documenting `(str)` against `int | str` signatures. **After:** enums live in exactly one place; `grep "(str)"` against signatures comes back clean; `pytest -q` → 242 passed with **zero test edits** (the wire format is unchanged — `timeAgoValue` is `str()`-ed in `_aggregations_query`), `mypy` → clean. ## Merge Danger **Door:** two-way **Blast Radius:** none — docstrings + a cosmetic default change with identical wire format. Closes #184. Closes #186. Closes #188.
📝 docs: dedupe aggregation time-window docstrings, fix type drift and time_ago_value default
All checks were successful
Tests / forgejo-pytest (push) Successful in 44s
Tests / forgejo-pytest (pull_request) Successful in 43s
84e64be4b1
mat force-pushed docs/agg-docstring-overhaul from 84e64be4b1
All checks were successful
Tests / forgejo-pytest (push) Successful in 44s
Tests / forgejo-pytest (pull_request) Successful in 43s
to 51adc2e8f7
All checks were successful
Tests / forgejo-pytest (push) Successful in 45s
Tests / forgejo-pytest (pull_request) Successful in 45s
2026-10-27 14:38:58 +00:00
Compare
mat changed title from WIP: 📝 docs: dedupe aggregation time-window docstrings, fix type drift and time_ago_value default to 📝 docs: dedupe aggregation time-window docstrings, fix type drift and time_ago_value default 2026-10-27 14:39:06 +00:00
mat merged commit 03d83f36fa into main 2026-10-27 14:39:08 +00:00
Sign in to join this conversation.
No reviewers
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!203
No description provided.