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

## 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.

Co-authored-by: Mateo Greil <mateo@go-electra.com>
Reviewed-on: https://git.greil.fr/mat/python-comwatt-client/pulls/44

Author: MateoGreil

README.md

@@ -13,8 +13,8 @@ The client currently supports the following methods:
 - `logout(self)`: Logs the current session out server-side (`POST /v1/logout`) and clears the stored credentials so `auto_reauth` cannot silently restore the session. Idempotent (a 401 when already logged out is a no-op). Note this is distinct from `close()`, which only releases the local HTTP session without logging out.
 - `get_authenticated_user(self)`: Retrieves information about the authenticated user.
 - `get_sites(self)`: Retrieves a list of sites associated with the authenticated user.
-- `get_site_networks_ts_time_ago(self, site_id, measure_kind = "FLOW", aggregation_level = "NONE", aggregation_type = None, time_ago_unit = "HOUR", time_ago_value = 1, start = None, end = None)`: Retrieves the time series data for the networks of a specific site, based on the provided parameters.
-- `get_site_consumption_breakdown_time_ago(self, site_id, aggregation_level = "HOUR", time_ago_unit = "DAY", time_ago_value = 1, start = None, end = None)` Retrieves the consumption breakdown data for a specific site, based on the provided parameters.
+- `get_site_networks_ts_time_ago(self, site_id, measure_kind = "FLOW", aggregation_level = "NONE", aggregation_type = None, time_ago_unit = "HOUR", time_ago_value = 1, start = None, end = None)`: Retrieves the time series data for the networks of a specific site, based on the provided parameters. **Deprecated** — use `get_site_time_series` instead (emits a `DeprecationWarning`; the endpoint still works but the app has moved to `site-time-series`).
+- `get_site_consumption_breakdown_time_ago(self, site_id, aggregation_level = "HOUR", time_ago_unit = "DAY", time_ago_value = 1, start = None, end = None)` Retrieves the consumption breakdown data for a specific site, based on the provided parameters. **Deprecated** — use `get_top_consumption` instead (emits a `DeprecationWarning`; the endpoint still works but the app has moved to `top-consumption`).
 - `get_devices(self, site_id)`: Retrieves a list of devices for the specified site.
 - `get_connected_objects(self, site_id=None, gateway_uid=None)`: Retrieves the connected objects for a site or a gateway. Exactly one of `site_id` / `gateway_uid` is required (raises `ValueError` otherwise).
 - `get_connected_object(self, connected_object_id)`: Retrieves information about a specific connected object.
@@ -68,13 +68,13 @@ print(user_info)
 sites = client.get_sites()
 print(sites)
 
-# Get time series data for the networks of a specific site
-networks_time_series_data = client.get_site_networks_ts_time_ago(sites[0]['id'])
-print(networks_time_series_data)
+# Get the whole-site rollup time series (productions, consumptions, injections, ...)
+site_time_series_data = client.get_site_time_series(sites[0]['id'])
+print(site_time_series_data)
 
-# Get the consumption breakdown data for a specific site, based on the provided parameters.
-consumption_breakdown_data = client.get_site_consumption_breakdown_time_ago(sites[0]['id'])
-print(consumption_breakdown_data)
+# Get the per-device consumption breakdown for a specific site (top 5 + "others")
+top_consumption_data = client.get_top_consumption(sites[0]['id'])
+print(top_consumption_data)
 
 # Get a list of devices for a specific site
 devices = client.get_devices(sites[0]['id'])

comwatt_client/_aggregations.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from datetime import datetime, timezone
 from typing import Any
 
@@ -76,8 +77,21 @@ def get_site_networks_ts_time_ago(self, site_id: int | str,
             ValueError: If `end` is given without `start`.
             Exception: If an error occurs while retrieving the data.
 
+        .. deprecated::
+            Use :meth:`get_site_time_series` instead. The
+            ``site-networks-ts-time-ago`` endpoint still responds, but the app
+            has moved to ``site-time-series``; this alias is kept only for
+            backward compatibility.
+
         """
 
+        warnings.warn(
+            "get_site_networks_ts_time_ago() is deprecated and will be removed in a "
+            "future release; use get_site_time_series() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         params = _aggregations_query(
             id_param="siteId", id_value=site_id, aggregation_level=aggregation_level,
             measure_kind=measure_kind, aggregation_type=aggregation_type,
@@ -115,8 +129,21 @@ def get_site_consumption_breakdown_time_ago(self, site_id: int | str,
             ValueError: If `end` is given without `start`.
             Exception: If an error occurs while retrieving the data.
 
+        .. deprecated::
+            Use :meth:`get_top_consumption` instead. The
+            ``consumption-breakdown-time-ago`` endpoint still responds, but the
+            app has moved to ``top-consumption``; this alias is kept only for
+            backward compatibility.
+
         """
 
+        warnings.warn(
+            "get_site_consumption_breakdown_time_ago() is deprecated and will be "
+            "removed in a future release; use get_top_consumption() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         params = _aggregations_query(
             id_param="siteId", id_value=site_id, aggregation_level=aggregation_level,
             time_ago_unit=time_ago_unit, time_ago_value=time_ago_value,

tests/test_aggregations.py

@@ -8,6 +8,7 @@
 from tests.conftest import BASE_URL
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_defaults(client):
     mock_data = {"values": [1, 2, 3]}
@@ -34,6 +35,7 @@ def test_get_site_networks_ts_time_ago_defaults(client):
     assert "aggregationType" not in qs
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_with_aggregation_type(client):
     mock_data = {"values": [4, 5, 6]}
@@ -53,6 +55,7 @@ def test_get_site_networks_ts_time_ago_with_aggregation_type(client):
     assert qs["aggregationType"] == ["SUM"]
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_custom_params(client):
     mock_data = {"values": [7, 8, 9]}
@@ -81,6 +84,7 @@ def test_get_site_networks_ts_time_ago_custom_params(client):
     assert qs["timeAgoValue"] == ["3"]
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_error(client):
     responses.add(
@@ -96,6 +100,7 @@ def test_get_site_networks_ts_time_ago_error(client):
     assert "500" in str(exc_info.value)
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_consumption_breakdown_time_ago_defaults(client):
     mock_data = {"breakdown": "data"}
@@ -120,6 +125,7 @@ def test_get_site_consumption_breakdown_time_ago_defaults(client):
     assert qs["timeAgoValue"] == ["1"]
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_consumption_breakdown_time_ago_custom_params(client):
     mock_data = {"breakdown": "custom"}
@@ -147,6 +153,7 @@ def test_get_site_consumption_breakdown_time_ago_custom_params(client):
     assert qs["timeAgoValue"] == ["2"]
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_consumption_breakdown_time_ago_error(client):
     responses.add(
@@ -188,6 +195,7 @@ def test_get_device_ts_time_ago_defaults(client):
     assert qs["timeAgoValue"] == ["1"]
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_with_naive_start(client):
     mock_data = {"values": [1]}
@@ -214,6 +222,7 @@ def test_get_site_networks_ts_time_ago_with_naive_start(client):
     assert qs["aggregationLevel"] == ["NONE"]
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_with_start_and_end(client):
     mock_data = {"values": [2]}
@@ -240,6 +249,7 @@ def test_get_site_networks_ts_time_ago_with_start_and_end(client):
     assert "timeAgoValue" not in qs
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_with_aware_start(client):
     mock_data = {"values": [3]}
@@ -260,6 +270,7 @@ def test_get_site_networks_ts_time_ago_with_aware_start(client):
     assert qs["start"] == ["2026-07-04T10:00:00Z"]
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_with_string_start(client):
     mock_data = {"values": [4]}
@@ -281,6 +292,7 @@ def test_get_site_networks_ts_time_ago_with_string_start(client):
     assert qs["start"] == ["2026-07-04T10:00:00Z"]
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_networks_ts_time_ago_end_without_start_raises(client):
     with pytest.raises(ValueError):
@@ -290,6 +302,7 @@ def test_get_site_networks_ts_time_ago_end_without_start_raises(client):
     assert len(responses.calls) == 0
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_consumption_breakdown_time_ago_with_start_and_end(client):
     mock_data = {"breakdown": "windowed"}
@@ -316,6 +329,7 @@ def test_get_site_consumption_breakdown_time_ago_with_start_and_end(client):
     assert "timeAgoValue" not in qs
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 @responses.activate
 def test_get_site_consumption_breakdown_time_ago_end_without_start_raises(client):
     with pytest.raises(ValueError):
@@ -702,3 +716,43 @@ def test_get_top_consumption_error(client):
         client.get_top_consumption("site-1")
 
     assert "500" in str(exc_info.value)
+
+
+@responses.activate
+def test_get_site_networks_ts_time_ago_is_deprecated(client):
+    mock_data = {"values": [1, 2, 3]}
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/aggregations/site-networks-ts-time-ago",
+        json=mock_data,
+        status=200,
+    )
+
+    with pytest.warns(DeprecationWarning, match="get_site_time_series") as record:
+        result = client.get_site_networks_ts_time_ago("site-1")
+
+    # Behaviour is unchanged: still returns the data and still hits the legacy endpoint.
+    assert result == mock_data
+    parsed = urlparse(responses.calls[0].request.url)
+    assert parsed.path == "/api/aggregations/site-networks-ts-time-ago"
+    # stacklevel=2 -> the warning is attributed to the caller (this test file).
+    assert record[0].filename == __file__
+
+
+@responses.activate
+def test_get_site_consumption_breakdown_time_ago_is_deprecated(client):
+    mock_data = {"breakdown": "data"}
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/aggregations/consumption-breakdown-time-ago",
+        json=mock_data,
+        status=200,
+    )
+
+    with pytest.warns(DeprecationWarning, match="get_top_consumption") as record:
+        result = client.get_site_consumption_breakdown_time_ago("site-1")
+
+    assert result == mock_data
+    parsed = urlparse(responses.calls[0].request.url)
+    assert parsed.path == "/api/aggregations/consumption-breakdown-time-ago"
+    assert record[0].filename == __file__