Add limit_reached property to Usage, deprecate limit_exceeded property

Author: daniel-jones-dev

CHANGELOG.md

@@ -10,8 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * New languages available: Indonesian (`'id'`) and Turkish (`'tr'`). Add language code constants and tests.
 
   Note: older library versions also support the new languages, this update only adds new code constants.
+* Add `limit_reached` and `any_limit_reached` properties to `Usage` object
+  returned by `get_usage()`.
 ### Changed
 ### Deprecated
+* Deprecate `limit_exceeded` and `any_limit_exceeded` properties of `Usage`
+  object returned by `get_usage()`, use `limit_reached` and `any_limit_reached`
+  instead.
 ### Removed
 ### Fixed
 ### Security

deepl/translator.py

@@ -218,7 +218,8 @@ class Usage:
     The character, document and team_document properties provide details about
     each corresponding usage type. These properties allow each usage type to be
     checked individually.
-    The any_limit_exceeded property checks if any usage type is exceeded.
+    The any_limit_reached property checks if for any usage type the amount used
+    has reached the allowed amount.
     """
 
     class Detail:
@@ -243,10 +244,21 @@ def valid(self) -> bool:
             return self._count is not None and self._limit is not None
 
         @property
-        def limit_exceeded(self) -> bool:
-            """True iff this limit is valid and exceeded."""
+        def limit_reached(self) -> bool:
+            """True if this limit is valid and the amount used is greater than
+            or equal to the amount allowed, otherwise False."""
             return self.valid and self.count >= self.limit
 
+        @property
+        def limit_exceeded(self) -> bool:
+            """Deprecated, use limit_reached instead."""
+            import warnings
+
+            warnings.warn(
+                "limit_reached is deprecated", DeprecationWarning, stacklevel=2
+            )
+            return self.limit_reached
+
         def __str__(self) -> str:
             return f"{self.count} of {self.limit}" if self.valid else "Unknown"
 
@@ -256,13 +268,24 @@ def __init__(self, json: dict):
         self._team_document = self.Detail(json, "team_document")
 
     @property
-    def any_limit_exceeded(self) -> bool:
-        """True if any API function limit is exceeded."""
+    def any_limit_reached(self) -> bool:
+        """True if for any API usage type, the amount used is greater than or
+        equal to the amount allowed, otherwise False."""
         return (
-            self.character.limit_exceeded
-            or self.document.limit_exceeded
-            or self.team_document.limit_exceeded
+            self.character.limit_reached
+            or self.document.limit_reached
+            or self.team_document.limit_reached
+        )
+
+    @property
+    def any_limit_exceeded(self) -> bool:
+        """Deprecated, use any_limit_reached instead."""
+        import warnings
+
+        warnings.warn(
+            "any_limit_reached is deprecated", DeprecationWarning, stacklevel=2
         )
+        return self.any_limit_reached
 
     @property
     def character(self) -> Detail:

tests/test_general.py

@@ -146,6 +146,11 @@ def test_usage_overrun(translator_with_random_auth_key, server, tmpdir):
     )
 
     usage = translator.get_usage()
+    assert usage.any_limit_reached
+    assert usage.document.limit_reached
+    assert usage.character.limit_reached
+    assert not usage.team_document.limit_reached
+    # Test deprecated properties as well
     assert usage.any_limit_exceeded
     assert usage.document.limit_exceeded
     assert usage.character.limit_exceeded
@@ -171,7 +176,7 @@ def test_usage_team_document_limit(
 
     translator = translator_with_random_auth_key
     usage = translator.get_usage()
-    assert not usage.any_limit_exceeded
+    assert not usage.any_limit_reached
     assert "Characters" not in str(usage)
     assert "Documents" not in str(usage)
     assert "Team documents: 0 of 1" in str(usage)
@@ -185,7 +190,7 @@ def test_usage_team_document_limit(
     )
 
     usage = translator.get_usage()
-    assert usage.any_limit_exceeded
-    assert not usage.document.limit_exceeded
-    assert not usage.character.limit_exceeded
-    assert usage.team_document.limit_exceeded
+    assert usage.any_limit_reached
+    assert not usage.document.limit_reached
+    assert not usage.character.limit_reached
+    assert usage.team_document.limit_reached