Collapse LimitGroup & LimitDecorator into Limit

The internal wrappers.LimitGroup and the LimitDecorator
exposed by the Limiter.limit & Limit.shared_limit decorators
had a lot of overlapping functionality and by collapsing them
into flask_limiter.Limit, flask_limiter.RouteLimit,
flask_limiter.ApplicationLimit & flask_limiter.MetaLimit.

Limit (and it's subclasses) can now be used to pass in definitions for default,
application & meta limits.

RouteLimit can be constructed with an additional limiter parameter and
then used to decorate routes or blueprints directly, instead of going
through Limiter.limit or Limiter.shared_limit

Additionally, meta_limits can now be passed in to decorated limits and
also configured on default & application limits individiually instead of
globally.

Author: alisaifee

doc/source/api.rst

@@ -7,6 +7,22 @@ Extension
 ---------
 .. autoclass:: Limiter
 
+Limit objects
+--------------
+
+The following dataclasses can be used to define rate limits with more
+granularity than what is available through the :class:`Limiter` constructor
+if needed (especially for **default**, **application wide** and **meta** limits).
+
+.. autoclass:: Limit
+.. autoclass:: ApplicationLimit
+.. autoclass:: MetaLimit
+
+For consistency the :class:`RouteLimit` dataclass is also available to define limits
+for decorating routes or blueprints.
+
+.. autoclass:: RouteLimit
+
 Utilities
 ---------
 .. autoclass:: ExemptionScope

examples/kitchensink.py

@@ -82,7 +82,9 @@ def health():
     #: Exempt from default, application and ancestor rate limits (effectively all)
     limiter.exempt(
         health_blueprint,
-        flags=ExemptionScope.DEFAULT | ExemptionScope.APPLICATION | ExemptionScope.ANCESTORS,
+        flags=ExemptionScope.DEFAULT
+        | ExemptionScope.APPLICATION
+        | ExemptionScope.ANCESTORS,
     )
 
     class ResourceView(View):

flask_limiter/__init__.py

@@ -6,11 +6,21 @@
 from .constants import ExemptionScope, HeaderNames
 from .errors import RateLimitExceeded
 from .extension import Limiter, RequestLimit
+from .limits import (
+    ApplicationLimit,
+    Limit,
+    MetaLimit,
+    RouteLimit,
+)
 
 __all__ = [
     "ExemptionScope",
     "HeaderNames",
     "Limiter",
+    "Limit",
+    "RouteLimit",
+    "ApplicationLimit",
+    "MetaLimit",
     "RateLimitExceeded",
     "RequestLimit",
 ]

flask_limiter/commands.py

@@ -23,9 +23,9 @@
 
 from flask_limiter import Limiter
 from flask_limiter.constants import ConfigVars, ExemptionScope, HeaderNames
+from flask_limiter.limits import RuntimeLimit
 from flask_limiter.typing import Callable, Generator, cast
 from flask_limiter.util import get_qualified_name
-from flask_limiter.wrappers import Limit
 
 limiter_theme = Theme(
     {
@@ -71,7 +71,7 @@ def render_strategy(strategy: RateLimiter) -> str:
 
 
 def render_limit_state(
-    limiter: Limiter, endpoint: str, limit: Limit, key: str, method: str
+    limiter: Limiter, endpoint: str, limit: RuntimeLimit, key: str, method: str
 ) -> str:
     args = [key, limit.scope_for(endpoint, method)]
     if not limiter.storage or (limiter.storage and not limiter.storage.check()):
@@ -86,7 +86,7 @@ def render_limit_state(
         return f": [success]Pass[/success] ({stats[1]} out of {limit.limit.amount} remaining)"
 
 
-def render_limit(limit: Limit, simple: bool = True) -> str:
+def render_limit(limit: RuntimeLimit, simple: bool = True) -> str:
     render = str(limit.limit)
     if simple:
         return render
@@ -103,7 +103,7 @@ def render_limit(limit: Limit, simple: bool = True) -> str:
 def render_limits(
     app: Flask,
     limiter: Limiter,
-    limits: tuple[list[Limit], ...],
+    limits: tuple[list[RuntimeLimit], ...],
     endpoint: str | None = None,
     blueprint: str | None = None,
     rule: Rule | None = None,
@@ -511,7 +511,7 @@ def clear(
 
             class Details(TypedDict):
                 rule: Rule
-                limits: tuple[list[Limit], ...]
+                limits: tuple[list[RuntimeLimit], ...]
 
             rule_limits: dict[str, Details] = {}
             for rule in sorted(

flask_limiter/errors.py

@@ -5,13 +5,13 @@
 from flask.wrappers import Response
 from werkzeug import exceptions
 
-from .wrappers import Limit
+from .limits import RuntimeLimit
 
 
 class RateLimitExceeded(exceptions.TooManyRequests):
     """Exception raised when a rate limit is hit."""
 
-    def __init__(self, limit: Limit, response: Response | None = None) -> None:
+    def __init__(self, limit: RuntimeLimit, response: Response | None = None) -> None:
         """
         :param limit: The actual rate limit that was hit.
          Used to construct the default response message