<commit_before>.. _pymemcache: https://pypi.python.org/pypi/pymemcache
.. _redis: https://pypi.python.org/pypi/redis
.. _github issue #41: https://github.com/alisaifee/flask-limiter/issues/41
.. _flask apps and ip spoofing: http://esd.io/blog/flask-apps-heroku-real-ip-spoofing.html

.. image:: _static/logo.png
    :target: /
    :width: 600px
    :align: center
    :class: logo

=============
Flask-Limiter
=============

.. currentmodule:: flask_limiter

.. toctree::
   :maxdepth: 2
   :hidden:

   strategies
   configuration
   recipes
   cli
   api
   development
   changelog
   misc


.. container:: badges

   .. image:: https://img.shields.io/github/last-commit/alisaifee/flask-limiter?logo=github&style=for-the-badge&labelColor=#282828
      :target: https://github.com/alisaifee/flask-limiter
      :class: header-badge
   .. image:: https://img.shields.io/github/workflow/status/alisaifee/flask-limiter/CI?logo=github&style=for-the-badge&labelColor=#282828
      :target: https://github.com/alisaifee/flask-limiter/actions/workflows/main.yml
      :class: header-badge
   .. image:: https://img.shields.io/codecov/c/github/alisaifee/flask-limiter?logo=codecov&style=for-the-badge&labelColor=#282828
      :target: https://app.codecov.io/gh/alisaifee/flask-limiter
      :class: header-badge
   .. image:: https://img.shields.io/pypi/pyversions/flask-limiter?style=for-the-badge&logo=pypi
      :target: https://pypi.org/project/flask-limiter
      :class: header-badge

**Flask-Limiter** provides rate limiting features to :class:`~flask.Flask` applications.

By adding the extension to your flask application, you can configure various
rate limits at different levels (e.g. application wide, per :class:`~flask.Blueprint`,
routes, resource etc).

**Flask-Limiter** can be configured to persist the rate limit state to many
commonly used storage backends via the :doc:`limits:index` library.


Let's get started!

Installation
============

**Flask-Limiter** can be installed via :program:`pip`.

.. code:: console

  $ pip install Flask-Limiter

To include extra dependencies for a specific storage backend you can add the
specific backend name via the ``extras`` notation. For example:

.. tab:: Redis

   .. code:: console

      $ pip install Flask-Limiter[redis]

.. tab:: Memcached

   .. code:: console

      $ pip install Flask-Limiter[memcached]

.. tab:: MongoDB

   .. code:: console

      $ pip install Flask-Limiter[mongodb]


Quick start
===========
A very basic setup can be achieved as follows:

.. code-block:: python

   from flask import Flask
   from flask_limiter import Limiter
   from flask_limiter.util import get_remote_address

   app = Flask(__name__)
   limiter = Limiter(
       app,
       key_func=get_remote_address,
       default_limits=["200 per day", "50 per hour"],
       storage_uri="memory://",
   )
   @app.route("/slow")
   @limiter.limit("1 per day")
   def slow():
       return ":("

   @app.route("/medium")
   @limiter.limit("1/second", override_defaults=False)
   def medium():
       return ":|"

   @app.route("/fast")
   def fast():
       return ":)"

   @app.route("/ping")
   @limiter.exempt
   def ping():
       return "PONG"


The above Flask app will have the following rate limiting characteristics:

* Use an in-memory storage provided by :class:`limits.storage.MemoryStorage`.

  .. note:: This is only meant for testing/development and should be replaced with
     an appropriate storage of your choice before moving to production.
* Rate limiting by the ``remote_address`` of the request
* A default rate limit of 200 per day, and 50 per hour applied to all routes.
* The ``slow`` route having an explicit rate limit decorator will bypass the default
  rate limit and only allow 1 request per day.
* The ``medium`` route inherits the default limits and adds on a decorated limit
  of 1 request per second.
* The ``ping`` route will be exempt from any default rate limits.

.. note:: The built in flask static files routes are also exempt from rate limits.

Every time a request exceeds the rate limit, the view function will not get called and instead
a `429 <http://tools.ietf.org/html/rfc6585#section-4>`_ http error will be raised.


The Flask-Limiter extension
---------------------------
The extension can be initialized with the :class:`flask.Flask` application
in the usual ways.

Using the constructor

   .. code-block:: python
<commit_msg>Use tip for hint about static routes in quickstart<commit_after>.. _pymemcache: https://pypi.python.org/pypi/pymemcache
.. _redis: https://pypi.python.org/pypi/redis
.. _github issue #41: https://github.com/alisaifee/flask-limiter/issues/41
.. _flask apps and ip spoofing: http://esd.io/blog/flask-apps-heroku-real-ip-spoofing.html

.. image:: _static/logo.png
    :target: /
    :width: 600px
    :align: center
    :class: logo

=============
Flask-Limiter
=============

.. currentmodule:: flask_limiter

.. toctree::
   :maxdepth: 2
   :hidden:

   strategies
   configuration
   recipes
   cli
   api
   development
   changelog
   misc


.. container:: badges

   .. image:: https://img.shields.io/github/last-commit/alisaifee/flask-limiter?logo=github&style=for-the-badge&labelColor=#282828
      :target: https://github.com/alisaifee/flask-limiter
      :class: header-badge
   .. image:: https://img.shields.io/github/workflow/status/alisaifee/flask-limiter/CI?logo=github&style=for-the-badge&labelColor=#282828
      :target: https://github.com/alisaifee/flask-limiter/actions/workflows/main.yml
      :class: header-badge
   .. image:: https://img.shields.io/codecov/c/github/alisaifee/flask-limiter?logo=codecov&style=for-the-badge&labelColor=#282828
      :target: https://app.codecov.io/gh/alisaifee/flask-limiter
      :class: header-badge
   .. image:: https://img.shields.io/pypi/pyversions/flask-limiter?style=for-the-badge&logo=pypi
      :target: https://pypi.org/project/flask-limiter
      :class: header-badge

**Flask-Limiter** provides rate limiting features to :class:`~flask.Flask` applications.

By adding the extension to your flask application, you can configure various
rate limits at different levels (e.g. application wide, per :class:`~flask.Blueprint`,
routes, resource etc).

**Flask-Limiter** can be configured to persist the rate limit state to many
commonly used storage backends via the :doc:`limits:index` library.


Let's get started!

Installation
============

**Flask-Limiter** can be installed via :program:`pip`.

.. code:: console

  $ pip install Flask-Limiter

To include extra dependencies for a specific storage backend you can add the
specific backend name via the ``extras`` notation. For example:

.. tab:: Redis

   .. code:: console

      $ pip install Flask-Limiter[redis]

.. tab:: Memcached

   .. code:: console

      $ pip install Flask-Limiter[memcached]

.. tab:: MongoDB

   .. code:: console

      $ pip install Flask-Limiter[mongodb]


Quick start
===========
A very basic setup can be achieved as follows:

.. code-block:: python

   from flask import Flask
   from flask_limiter import Limiter
   from flask_limiter.util import get_remote_address

   app = Flask(__name__)
   limiter = Limiter(
       app,
       key_func=get_remote_address,
       default_limits=["200 per day", "50 per hour"],
       storage_uri="memory://",
   )
   @app.route("/slow")
   @limiter.limit("1 per day")
   def slow():
       return ":("

   @app.route("/medium")
   @limiter.limit("1/second", override_defaults=False)
   def medium():
       return ":|"

   @app.route("/fast")
   def fast():
       return ":)"

   @app.route("/ping")
   @limiter.exempt
   def ping():
       return "PONG"


The above Flask app will have the following rate limiting characteristics:

* Use an in-memory storage provided by :class:`limits.storage.MemoryStorage`.

  .. note:: This is only meant for testing/development and should be replaced with
     an appropriate storage of your choice before moving to production.
* Rate limiting by the ``remote_address`` of the request
* A default rate limit of 200 per day, and 50 per hour applied to all routes.
* The ``slow`` route having an explicit rate limit decorator will bypass the default
  rate limit and only allow 1 request per day.
* The ``medium`` route inherits the default limits and adds on a decorated limit
  of 1 request per second.
* The ``ping`` route will be exempt from any default rate limits.

  .. tip:: The built in flask static files routes are also exempt from rate limits.

Every time a request exceeds the rate limit, the view function will not get called and instead
a `429 <http://tools.ietf.org/html/rfc6585#section-4>`_ http error will be raised.


The Flask-Limiter extension
---------------------------
The extension can be initialized with the :class:`flask.Flask` application
in the usual ways.

Using the constructor

   .. code-block:: python

{'fraction_non_alphanumeric': 0.1303956834532374, 'fraction_numerical': 0.01079136690647482, 'mean_word_length': 3.419771485345256, 'pattern_counts': {'":': 6, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 22, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1960007', 'n_tokens_mistral': 2891, 'n_tokens_neox': 2715, 'n_words': 832}