fix: return known group_by and aggregate_by of admin reports as enum members

AdminUsageReport.group_by and CustomTagUsageReport.aggregate_by were always
the raw string, so comparing them with AdminUsageGroupBy or
CustomTagUsageAggregateBy members was never true. Unknown values are still
returned as the string.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

README.md

@@ -1315,8 +1315,10 @@ date raises a `ValueError` before any request is sent. Use
 `group_by` to break the usage down by key (`AdminUsageGroupBy.KEY`, see
 `key_usages`) or by key and day (`AdminUsageGroupBy.KEY_AND_DAY`, see
 `key_and_day_usages`). The lists are empty if the report is not grouped that
-way. The `group_by` and `aggregate_by` of a report are plain strings as the API
-names them, for example `"keyAndDay"`.
+way. The `group_by` of an `AdminUsageReport` and the `aggregate_by` of a
+`CustomTagUsageReport` are `AdminUsageGroupBy` and `CustomTagUsageAggregateBy`
+members for known values; a value this library does not know is returned as
+the string the API sent.
 
 ```python
 report = admin_client.get_usage_analytics(

deepl/api_data.py

@@ -2396,6 +2396,24 @@ def _str_or_none(value: Any) -> Optional[str]:
     return value if isinstance(value, str) else None
 
 
+def _group_by_or_none(value: Any) -> Union[AdminUsageGroupBy, str, None]:
+    # The live API answers group_by=key_and_day with "keyAndDay".
+    if value == "keyAndDay":
+        return AdminUsageGroupBy.KEY_AND_DAY
+    return _open_enum(AdminUsageGroupBy, value)
+
+
+def _open_enum(enum_type: Any, value: Any) -> Any:
+    """Returns the enum member for a known value, an unknown string as is,
+    and None for anything else."""
+    if not isinstance(value, str):
+        return None
+    try:
+        return enum_type(value)
+    except ValueError:
+        return value
+
+
 def _limit_or_none(json: dict, key: str) -> Optional[int]:
     return None if isinstance(json.get(key), bool) else get_int_safe(json, key)
 
@@ -2747,7 +2765,8 @@ class AdminUsageReport:
     :param total_usage: Usage totals over the whole date range.
     :param start_date: Start of the report period.
     :param end_date: End of the report period.
-    :param group_by: Grouping used for the report, if any.
+    :param group_by: Grouping used for the report: an AdminUsageGroupBy for a
+        known value, the string for an unknown one, or None.
     :param key_usages: Usage per key, present when grouped by key.
     :param key_and_day_usages: Usage per key and day, present when grouped by
         key and day.
@@ -2758,7 +2777,7 @@ def __init__(
         total_usage: AdminUsageBreakdown,
         start_date: Optional[datetime.datetime],
         end_date: Optional[datetime.datetime],
-        group_by: Optional[str] = None,
+        group_by: Union[AdminUsageGroupBy, str, None] = None,
         key_usages: Optional[List[KeyUsage]] = None,
         key_and_day_usages: Optional[List[KeyUsage]] = None,
     ):
@@ -2779,7 +2798,7 @@ def from_json(json: Any) -> "AdminUsageReport":
             ),
             start_date=_parse_utc_timestamp(report.get("start_date")),
             end_date=_parse_utc_timestamp(report.get("end_date")),
-            group_by=_str_or_none(report.get("group_by")),
+            group_by=_group_by_or_none(report.get("group_by")),
             key_usages=[
                 KeyUsage.from_json(item)
                 for item in _dict_items(report.get("key_usages"))
@@ -2806,9 +2825,9 @@ def end_date(self) -> Optional[datetime.datetime]:
         return self._end_date
 
     @property
-    def group_by(self) -> Optional[str]:
-        """Returns the grouping used for the report as the API returns it
-        (currently "key" or "keyAndDay"), or None."""
+    def group_by(self) -> Union[AdminUsageGroupBy, str, None]:
+        """Returns the grouping used for the report as an AdminUsageGroupBy,
+        the string the API sent if it is not a known value, or None."""
         return self._group_by
 
     @property
@@ -2932,7 +2951,9 @@ def usage_date(self) -> Optional[datetime.datetime]:
 class CustomTagUsageReport:
     """Admin custom tag usage analytics report for a date range.
 
-    :param aggregate_by: Aggregation used for the report.
+    :param aggregate_by: Aggregation used for the report: a
+        CustomTagUsageAggregateBy for a known value, the string for an
+        unknown one, or None.
     :param start_date: Start of the report period.
     :param end_date: End of the report period.
     :param next_page: Page number to request the next page, or None if this
@@ -2942,7 +2963,7 @@ class CustomTagUsageReport:
 
     def __init__(
         self,
-        aggregate_by: Optional[str],
+        aggregate_by: Union[CustomTagUsageAggregateBy, str, None],
         start_date: Optional[datetime.datetime],
         end_date: Optional[datetime.datetime],
         next_page: Optional[int],
@@ -2959,7 +2980,9 @@ def from_json(json: Any) -> "CustomTagUsageReport":
         """Create CustomTagUsageReport from the given API JSON object."""
         report = _as_dict(_as_dict(json).get("custom_tag_usage_report"))
         return CustomTagUsageReport(
-            aggregate_by=_str_or_none(report.get("aggregate_by")),
+            aggregate_by=_open_enum(
+                CustomTagUsageAggregateBy, report.get("aggregate_by")
+            ),
             start_date=_parse_utc_timestamp(report.get("start_date")),
             end_date=_parse_utc_timestamp(report.get("end_date")),
             next_page=get_int_safe(report, "next_page"),
@@ -2970,9 +2993,10 @@ def from_json(json: Any) -> "CustomTagUsageReport":
         )
 
     @property
-    def aggregate_by(self) -> Optional[str]:
-        """Returns the aggregation used for the report as the API returns it
-        (e.g. "period" or "day"), or None."""
+    def aggregate_by(self) -> Union[CustomTagUsageAggregateBy, str, None]:
+        """Returns the aggregation used for the report as a
+        CustomTagUsageAggregateBy, the string the API sent if it is not a
+        known value, or None."""
         return self._aggregate_by
 
     @property

tests/offline/test_admin_client.py

@@ -93,7 +93,7 @@ def test_get_usage_analytics(mocked):
 
     assert report.total_usage.speech_to_text_minutes == 107.46
     assert report.total_usage.speech_to_speech_minutes == 3.5
-    assert report.group_by == "keyAndDay"
+    assert report.group_by is deepl.AdminUsageGroupBy.KEY_AND_DAY
     assert report.start_date == datetime.datetime(2025, 9, 29, tzinfo=UTC)
     assert report.key_usages == []
     usage = report.key_and_day_usages[0]
@@ -144,7 +144,7 @@ def test_get_custom_tag_usage_analytics(mocked):
         page=2,
     )
 
-    assert report.aggregate_by == "day"
+    assert report.aggregate_by is deepl.CustomTagUsageAggregateBy.DAY
     assert report.next_page == 3
     assert report.usage[0].breakdown.speech_to_speech_minutes == 4.2
     assert report.usage[0].usage_date == datetime.datetime(
@@ -153,6 +153,49 @@ def test_get_custom_tag_usage_analytics(mocked):
     assert report.end_date == datetime.datetime(2026, 5, 15, tzinfo=UTC)
 
 
+@pytest.mark.parametrize(
+    "group_by, expected",
+    [
+        ("key", deepl.AdminUsageGroupBy.KEY),
+        ("key_and_day", deepl.AdminUsageGroupBy.KEY_AND_DAY),
+        ("by_team", "by_team"),
+    ],
+)
+def test_report_group_by_is_open_enum(mocked, group_by, expected):
+    mocked.get(
+        url("v2/admin/analytics"),
+        json={"usage_report": {"group_by": group_by}},
+    )
+
+    report = make_admin_client().get_usage_analytics(
+        "2026-05-03", "2026-05-04"
+    )
+
+    assert report.group_by == expected
+    assert type(report.group_by) is type(expected)
+
+
+@pytest.mark.parametrize(
+    "aggregate_by, expected",
+    [
+        ("period", deepl.CustomTagUsageAggregateBy.PERIOD),
+        ("week", "week"),
+    ],
+)
+def test_report_aggregate_by_is_open_enum(mocked, aggregate_by, expected):
+    mocked.get(
+        url("v2/admin/analytics/custom-tags"),
+        json={"custom_tag_usage_report": {"aggregate_by": aggregate_by}},
+    )
+
+    report = make_admin_client().get_custom_tag_usage_analytics(
+        "2026-05-03", "2026-05-04"
+    )
+
+    assert report.aggregate_by == expected
+    assert type(report.aggregate_by) is type(expected)
+
+
 def test_uses_utc_date_of_datetime(mocked):
     mocked.get(
         url("v2/admin/analytics"),

tests/real_api/test_admin_client.py

@@ -27,7 +27,7 @@ def test_get_usage_analytics():
     assert report.start_date is not None
     assert report.start_date.tzinfo is not None
     assert report.end_date is not None
-    assert report.group_by == "keyAndDay"
+    assert report.group_by is deepl.AdminUsageGroupBy.KEY_AND_DAY
 
 
 def test_get_custom_tag_usage_analytics():
@@ -39,7 +39,7 @@ def test_get_custom_tag_usage_analytics():
 
     assert report.start_date is not None
     assert report.end_date is not None
-    assert report.aggregate_by == "day"
+    assert report.aggregate_by is deepl.CustomTagUsageAggregateBy.DAY
     assert isinstance(report.usage, list)