mat/python-comwatt-client
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

🗑️ Deprecate the two *-time-ago aggregation methods #44

Merged
mat merged 1 commit from deprecate-time-ago into main 2026-07-08 09:01:15 +00:00
Conversation 0 Commits 1 Files changed 3 +89 -8
mat commented 2026-07-05 10:10:12 +00:00
Owner
Copy link

Summary

Soft-deprecates the two legacy aggregation aliases in favour of their current-spelling replacements:

  • get_site_networks_ts_time_ago → get_site_time_series
  • get_site_consumption_breakdown_time_ago → get_top_consumption

Both legacy methods now emit a DeprecationWarning (with stacklevel=2, so it points at the caller) but are otherwise unchanged: same endpoints (site-networks-ts-time-ago / consumption-breakdown-time-ago, both still returning 200 live), same defaults, same response shape. Nothing is removed — existing callers (e.g. the Home Assistant integration) keep working without changes.

Why not just delete them / re-point them at the new endpoints? Because the new methods have different defaults (aggregation_level NONE→HOUR, time_ago_unit HOUR→DAY), so delegating would silently change behaviour for callers relying on defaults. A pure soft-deprecation is zero-risk.

Changes

  • comwatt_client/_aggregations.py: warnings.warn(..., DeprecationWarning, stacklevel=2) at the top of both methods + a .. deprecated:: docstring note.
  • tests/test_aggregations.py: two new tests asserting the warning category/message and that behaviour (endpoint + returned data) is unchanged; the existing legacy-method tests get a per-test @pytest.mark.filterwarnings("ignore::DeprecationWarning") so the project's global filterwarnings = error policy stays intact everywhere else.
  • README.md: both methods flagged Deprecated in the feature list; usage example switched to get_site_time_series / get_top_consumption.

Not included (by request)

  • No version bump / release commit — releases are separate commits in this repo.

Test plan

  • pytest → 94 passed (2 new).
  • mypy comwatt_client → clean.
  • filterwarnings = error kept globally; only the legacy-method tests opt out.

Opened as a draft (WIP) — mark ready for review when you're happy.

## Summary Soft-deprecates the two legacy aggregation aliases in favour of their current-spelling replacements: - `get_site_networks_ts_time_ago` → **`get_site_time_series`** - `get_site_consumption_breakdown_time_ago` → **`get_top_consumption`** Both legacy methods now emit a `DeprecationWarning` (with `stacklevel=2`, so it points at the caller) but are **otherwise unchanged**: same endpoints (`site-networks-ts-time-ago` / `consumption-breakdown-time-ago`, both still returning `200` live), same defaults, same response shape. Nothing is removed — existing callers (e.g. the Home Assistant integration) keep working without changes. Why not just delete them / re-point them at the new endpoints? Because the new methods have **different defaults** (`aggregation_level` NONE→HOUR, `time_ago_unit` HOUR→DAY), so delegating would silently change behaviour for callers relying on defaults. A pure soft-deprecation is zero-risk. ## Changes - `comwatt_client/_aggregations.py`: `warnings.warn(..., DeprecationWarning, stacklevel=2)` at the top of both methods + a `.. deprecated::` docstring note. - `tests/test_aggregations.py`: two new tests asserting the warning category/message and that behaviour (endpoint + returned data) is unchanged; the existing legacy-method tests get a per-test `@pytest.mark.filterwarnings("ignore::DeprecationWarning")` so the project's global `filterwarnings = error` policy stays intact everywhere else. - `README.md`: both methods flagged **Deprecated** in the feature list; usage example switched to `get_site_time_series` / `get_top_consumption`. ## Not included (by request) - No version bump / release commit — releases are separate commits in this repo. ## Test plan - [x] `pytest` → 94 passed (2 new). - [x] `mypy comwatt_client` → clean. - [x] `filterwarnings = error` kept globally; only the legacy-method tests opt out. Opened as a draft (WIP) — mark ready for review when you're happy.
🗑️ Deprecate the two *-time-ago aggregation methods
All checks were successful
Tests / forgejo-pytest (push) Successful in 43s
Details
Tests / forgejo-pytest (pull_request) Successful in 43s
Details
44f6f02018 
get_site_networks_ts_time_ago and get_site_consumption_breakdown_time_ago
now emit a DeprecationWarning pointing at their current-spelling
replacements (get_site_time_series / get_top_consumption).

Behaviour is intentionally unchanged: they still call the same
site-networks-ts-time-ago / consumption-breakdown-time-ago endpoints
(which still return 200) with the same defaults, so existing callers
(e.g. the Home Assistant integration) keep working. Only a warning is
added — no forced migration.

- warnings.warn(..., DeprecationWarning, stacklevel=2) in both methods
- new tests assert the warning category/message and that behaviour is
  unchanged; existing legacy-method tests keep filterwarnings=error via
  a per-test ignore marker
- README: mark both methods deprecated and switch the usage example to
  the new methods
mat changed title from WIP: 🗑️ Deprecate the two *-time-ago aggregation methods to 🗑️ Deprecate the two *-time-ago aggregation methods 2026-07-08 09:01:10 +00:00
mat merged commit f2c1366f3e into main 2026-07-08 09:01:15 +00:00
mat deleted branch deprecate-time-ago 2026-07-08 09:01:15 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
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!44
No description provided.