Command Line Interface¶
New in version 2.4.0.
Flask-Limiter adds a few subcommands to the Flask flask:cli for maintenance & diagnostic purposes. These can be accessed under the limiter sub-command as follows
Error: While importing 'kitchensink', an ImportError was raised:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/flask/cli.py", line 260, in locate_app
__import__(module_name)
File "/build/flask-limiter-cEscow/flask-limiter-2.6.2/examples/kitchensink.py", line 5, in <module>
import flask_limiter
ModuleNotFoundError: No module named 'flask_limiter'
Usage: flask [OPTIONS] COMMAND [ARGS]...
Try 'flask --help' for help.
Error: No such command 'limiter'.
Example¶
The examples below use the following example application:
import jinja2
from flask import Blueprint, Flask, jsonify, request, render_template, make_response
from flask.views import View
import flask_limiter
from flask_limiter import ExemptionScope, Limiter
from flask_limiter.util import get_remote_address
def index_error_responder(request_limit):
error_template = jinja2.Environment().from_string(
"""
<h1>Breached rate limit of: {{request_limit.limit}}</h1>
<h2>Path: {{request.path}}</h2>
"""
)
return make_response(render_template(error_template, request_limit=request_limit))
def app():
def default_limit_extra():
if request.headers.get("X-Evil"):
return "100/minute"
return "200/minute"
def default_cost():
if request.headers.get("X-Evil"):
return 2
return 1
limiter = Limiter(
key_func=get_remote_address,
default_limits=["20/hour", "1000/hour", default_limit_extra],
default_limits_exempt_when=lambda: request.headers.get("X-Internal"),
default_limits_deduct_when=lambda response: response.status_code == 200,
default_limits_cost=default_cost,
application_limits=["5000/hour"],
headers_enabled=True,
)
app = Flask(__name__)
app.config.from_prefixed_env()
@app.errorhandler(429)
def handle_error(e):
return e.get_response() or make_response(
jsonify(error="ratelimit exceeded %s" % e.description)
)
@app.route("/")
@limiter.limit("10/minute", on_breach=index_error_responder)
def root():
"""
Custom rate limit of 10/minute which overrides the default limits.
The error page displayed on rate limit breached is also customized by using
an `on_breach` callback to render a template
"""
return "42"
@app.route("/version")
@limiter.exempt
def version():
"""
Exempt from all rate limits
"""
return flask_limiter.__version__
health_blueprint = Blueprint("health", __name__, url_prefix="/health")
@health_blueprint.route("/")
def health():
return "ok"
app.register_blueprint(health_blueprint)
#: Exempt from default, application and ancestor rate limits (effectively all)
limiter.exempt(
health_blueprint,
flags=ExemptionScope.DEFAULT
| ExemptionScope.APPLICATION
| ExemptionScope.ANCESTORS,
)
class ResourceView(View):
methods = ["GET", "POST"]
@staticmethod
def json_error_responder(request_limit):
return jsonify({"limit": str(request_limit.limit)})
#: Custom rate limit of 5/second by http method type for all routes under this
#: resource view. The error response is also customized by using the `on_breach`
#: callback to return a json error response
decorators = [
limiter.limit("5/second", per_method=True, on_breach=json_error_responder)
]
def dispatch_request(self):
return request.method.lower()
app.add_url_rule("/resource", view_func=ResourceView.as_view("resource"))
limiter.init_app(app)
return app
if __name__ == "__main__":
app().run()
Extension Config¶
Use the subcommand config to display the active configuration
$ flask limiter config
$ FLASK_APP=../../examples/kitchensink.py:app flask limiter config
Error: While importing 'kitchensink', an ImportError was raised:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/flask/cli.py", line 260, in locate_app
__import__(module_name)
File "/build/flask-limiter-cEscow/flask-limiter-2.6.2/examples/kitchensink.py", line 5, in <module>
import flask_limiter
ModuleNotFoundError: No module named 'flask_limiter'
Usage: flask [OPTIONS] COMMAND [ARGS]...
Try 'flask --help' for help.
Error: No such command 'limiter'.
List limits¶
$ flask limiter limits
Use the subcommand limits to display all configured limits
$ FLASK_APP=../../examples/kitchensink.py:app flask limiter limits
Error: While importing 'kitchensink', an ImportError was raised:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/flask/cli.py", line 260, in locate_app
__import__(module_name)
File "/build/flask-limiter-cEscow/flask-limiter-2.6.2/examples/kitchensink.py", line 5, in <module>
import flask_limiter
ModuleNotFoundError: No module named 'flask_limiter'
Usage: flask [OPTIONS] COMMAND [ARGS]...
Try 'flask --help' for help.
Error: No such command 'limiter'.
Filter by endpoint name¶
$ FLASK_APP=../../examples/kitchensink.py:app flask limiter limits --endpoint=root
Error: While importing 'kitchensink', an ImportError was raised:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/flask/cli.py", line 260, in locate_app
__import__(module_name)
File "/build/flask-limiter-cEscow/flask-limiter-2.6.2/examples/kitchensink.py", line 5, in <module>
import flask_limiter
ModuleNotFoundError: No module named 'flask_limiter'
Usage: flask [OPTIONS] COMMAND [ARGS]...
Try 'flask --help' for help.
Error: No such command 'limiter'.
Filter by path¶
$ FLASK_APP=../../examples/kitchensink.py:app flask limiter limits --path=/health/
Error: While importing 'kitchensink', an ImportError was raised:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/flask/cli.py", line 260, in locate_app
__import__(module_name)
File "/build/flask-limiter-cEscow/flask-limiter-2.6.2/examples/kitchensink.py", line 5, in <module>
import flask_limiter
ModuleNotFoundError: No module named 'flask_limiter'
Usage: flask [OPTIONS] COMMAND [ARGS]...
Try 'flask --help' for help.
Error: No such command 'limiter'.
Check limit status¶
$ FLASK_APP=../../examples/kitchensink.py:app flask limiter limits --key=127.0.0.1
Error: While importing 'kitchensink', an ImportError was raised:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/flask/cli.py", line 260, in locate_app
__import__(module_name)
File "/build/flask-limiter-cEscow/flask-limiter-2.6.2/examples/kitchensink.py", line 5, in <module>
import flask_limiter
ModuleNotFoundError: No module named 'flask_limiter'
Usage: flask [OPTIONS] COMMAND [ARGS]...
Try 'flask --help' for help.
Error: No such command 'limiter'.
Clear limits¶
$ flask limiter clear
The CLI exposes a subcommand clear that can be used to clear either all limits or limits for specific endpoints or routes by a
key
which represents the value returned by the key_func
(i.e. a specific user)
callable configured for your application.
$ FLASK_APP=../../examples/kitchensink.py:app flask limiter clear --help
Error: While importing 'kitchensink', an ImportError was raised:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/flask/cli.py", line 260, in locate_app
__import__(module_name)
File "/build/flask-limiter-cEscow/flask-limiter-2.6.2/examples/kitchensink.py", line 5, in <module>
import flask_limiter
ModuleNotFoundError: No module named 'flask_limiter'
Usage: flask [OPTIONS] COMMAND [ARGS]...
Try 'flask --help' for help.
Error: No such command 'limiter'.
By default this is an interactive command which requires confirmation, however it can
also be used in automations by using the -y
flag to force confirmation.
$ FLASK_APP=../../examples/kitchensink.py:app flask limiter clear --key=127.0.0.1 -y
Error: While importing 'kitchensink', an ImportError was raised:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/flask/cli.py", line 260, in locate_app
__import__(module_name)
File "/build/flask-limiter-cEscow/flask-limiter-2.6.2/examples/kitchensink.py", line 5, in <module>
import flask_limiter
ModuleNotFoundError: No module named 'flask_limiter'
Usage: flask [OPTIONS] COMMAND [ARGS]...
Try 'flask --help' for help.
Error: No such command 'limiter'.