# API

## Storage

class `limits.storage.``Storage`(uri=None, **options)

  Bases: `object`

  Base class to extend when implementing a storage backend.

  `check`()

    check if storage is healthy

  `get`(key)

    Parameters: | key (str) – the key to get the counter value for

  `get_expiry`(key)

    Parameters: | key (str) – the key to get the expiry for

  `incr`(key, expiry, elastic_expiry=False)

    increments the counter for a given rate limit key

    Parameters:

    - key (str) – the key to increment
    - expiry (int) – amount in seconds for the key to expire in
    - elastic_expiry (bool) – whether to keep extending the rate limit window every hit.

  `reset`()

    reset storage to clear limits

class `limits.storage.``MemoryStorage`(uri=None, **_)

  Bases: `limits.storage.Storage`

  rate limit storage using `collections.Counter` as an in memory storage for fixed and elastic window strategies, and a simple list to implement moving window strategy.

  `acquire_entry`(key, limit, expiry, no_add=False)

    Parameters:

    - key (str) – rate limit key to acquire an entry in
    - limit (int) – amount of entries allowed
    - expiry (int) – expiry of the entry
    - no_add (bool) – if False an entry is not actually acquired but instead serves as a ‘check’

    Returns: | True/False

  `check`()

    check if storage is healthy

  `get`(key)

    Parameters: | key (str) – the key to get the counter value for

  `get_expiry`(key)

    Parameters: | key (str) – the key to get the expiry for

  `get_moving_window`(key, limit, expiry)

    returns the starting point and the number of entries in the moving window

    Parameters:

    - key (str) – rate limit key
    - expiry (int) – expiry of entry

  `get_num_acquired`(key, expiry)

    returns the number of entries already acquired

    Parameters:

    - key (str) – rate limit key to acquire an entry in
    - expiry (int) – expiry of the entry

  `incr`(key, expiry, elastic_expiry=False)

    increments the counter for a given rate limit key

    Parameters:

    - key (str) – the key to increment
    - expiry (int) – amount in seconds for the key to expire in
    - elastic_expiry (bool) – whether to keep extending the rate limit window every hit.

class `limits.storage.``RedisStorage`(uri, **_)

  Bases: `limits.storage.RedisInteractor`, `limits.storage.Storage`

  rate limit storage with redis as backend

  `acquire_entry`(key, limit, expiry, no_add=False)

    Parameters:

    - key (str) – rate limit key to acquire an entry in
    - limit (int) – amount of entries allowed
    - expiry (int) – expiry of the entry
    - no_add (bool) – if False an entry is not actually acquired but instead serves as a ‘check’

    Returns: | True/False

  `check`()

    check if storage is healthy

  `get`(key)

    Parameters: | key (str) – the key to get the counter value for

  `get_expiry`(key)

    Parameters: | key (str) – the key to get the expiry for

  `incr`(key, expiry, elastic_expiry=False)

    increments the counter for a given rate limit key

    Parameters:

    - key (str) – the key to increment
    - expiry (int) – amount in seconds for the key to expire in

  `reset`()

    WARNING, this operation was designed to be fast, but was not tested on a large production based system. Be careful with its usage as it could be slow on very large data sets.

    This function calls a Lua Script to delete keys prefixed with ‘LIMITER’ in block of 5000.

class `limits.storage.``RedisSentinelStorage`(uri, **options)

  Bases: `limits.storage.RedisStorage`

  rate limit storage with redis sentinel as backend

  `check`()

    check if storage is healthy

  `get`(key)

    Parameters: | key (str) – the key to get the counter value for

  `get_expiry`(key)

    Parameters: | key (str) – the key to get the expiry for

class `limits.storage.``MemcachedStorage`(uri, **options)

  Bases: `limits.storage.Storage`

  rate limit storage with memcached as backend

  `check`()

    check if storage is healthy

  `get`(key)

    Parameters: | key (str) – the key to get the counter value for

  `get_client`(module, hosts)

    returns a memcached client. :param module: the memcached module :param hosts: list of memcached hosts :return:

  `get_expiry`(key)

    Parameters: | key (str) – the key to get the expiry for

  `incr`(key, expiry, elastic_expiry=False)

    increments the counter for a given rate limit key

    Parameters:

    - key (str) – the key to increment
    - expiry (int) – amount in seconds for the key to expire in
    - elastic_expiry (bool) – whether to keep extending the rate limit window every hit.

  `storage`

    lazily creates a memcached client instance using a thread local

`limits.storage.``storage_from_string`(storage_string, **options)

  factory function to get an instance of the storage class based on the uri of the storage

  Parameters: | storage_string – a string of the form method://host:port
  Returns: | an instance of `flask_limiter.storage.Storage`

## Strategies

class `limits.strategies.``RateLimiter`(storage)

  Bases: `object`

  `get_window_stats`(item, *identifiers)

    returns the number of requests remaining and reset of this limit.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | tuple (reset time (int), remaining (int))

  `hit`(item, *identifiers)

    creates a hit on the rate limit and returns True if successful.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | True/False

  `test`(item, *identifiers)

    checks the rate limit and returns True if it is not currently exceeded.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | True/False

class `limits.strategies.``FixedWindowRateLimiter`(storage)

  Bases: `limits.strategies.RateLimiter`

  Reference: Fixed Window

  `get_window_stats`(item, *identifiers)

    returns the number of requests remaining and reset of this limit.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | tuple (reset time (int), remaining (int))

  `hit`(item, *identifiers)

    creates a hit on the rate limit and returns True if successful.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | True/False

  `test`(item, *identifiers)

    checks the rate limit and returns True if it is not currently exceeded.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | True/False

class `limits.strategies.``FixedWindowElasticExpiryRateLimiter`(storage)

  Bases: `limits.strategies.FixedWindowRateLimiter`

  Reference: Fixed Window with Elastic Expiry

  `hit`(item, *identifiers)

    creates a hit on the rate limit and returns True if successful.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | True/False

class `limits.strategies.``MovingWindowRateLimiter`(storage)

  Bases: `limits.strategies.RateLimiter`

  Reference: Moving Window

  `get_window_stats`(item, *identifiers)

    returns the number of requests remaining within this limit.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | tuple (reset time (int), remaining (int))

  `hit`(item, *identifiers)

    creates a hit on the rate limit and returns True if successful.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | True/False

  `test`(item, *identifiers)

    checks the rate limit and returns True if it is not currently exceeded.

    Parameters:

    - item – a `RateLimitItem` instance
    - identifiers – variable list of strings to uniquely identify the limit

    Returns: | True/False

## Rate Limits

class `limits.``RateLimitItem`(amount, multiples=1, namespace='LIMITER')

  Bases: `object`

  defines a Rate limited resource which contains the characteristic namespace, amount and granularity multiples of the rate limiting window.

  Parameters:

  - amount (int) – the rate limit amount
  - multiples (int) – multiple of the ‘per’ granularity (e.g. ‘n’ per ‘m’ seconds)
  - namespace (string) – category for the specific rate limit

  classmethod `check_granularity_string`(granularity_string)

    checks if this instance matches a granularity string of type ‘n per hour’ etc.

    Returns: | True/False

  `get_expiry`()

    Returns: | the size of the window in seconds.

  `key_for`(*identifiers)

    Parameters: | identifiers – a list of strings to append to the key
    Returns: | a string key identifying this resource with each identifier appended with a ‘/’ delimiter.

class `limits.``RateLimitItemPerYear`(amount, multiples=1, namespace='LIMITER')

  Bases: `limits.limits.RateLimitItem`

  per year rate limited resource.

class `limits.``RateLimitItemPerMonth`(amount, multiples=1, namespace='LIMITER')

  Bases: `limits.limits.RateLimitItem`

  per month rate limited resource.

class `limits.``RateLimitItemPerDay`(amount, multiples=1, namespace='LIMITER')

  Bases: `limits.limits.RateLimitItem`

  per day rate limited resource.

class `limits.``RateLimitItemPerHour`(amount, multiples=1, namespace='LIMITER')

  Bases: `limits.limits.RateLimitItem`

  per hour rate limited resource.

class `limits.``RateLimitItemPerMinute`(amount, multiples=1, namespace='LIMITER')

  Bases: `limits.limits.RateLimitItem`

  per minute rate limited resource.

class `limits.``RateLimitItemPerSecond`(amount, multiples=1, namespace='LIMITER')

  Bases: `limits.limits.RateLimitItem`

  per second rate limited resource.

`limits.``parse`(limit_string)

  parses a single rate limit in string notation (e.g. ‘1/second’ or ‘1 per second’

  Parameters: | limit_string (string) – rate limit string using Rate limit string notation
  Raises: | ValueError – if the string notation is invalid.
  Returns: | an instance of `RateLimitItem`

`limits.``parse_many`(limit_string)

  parses rate limits in string notation containing multiple rate limits (e.g. ‘1/second; 5/minute’)

  Parameters: | limit_string (string) – rate limit string using Rate limit string notation
  Raises: | ValueError – if the string notation is invalid.
  Returns: | a list of `RateLimitItem` instances.

## Exceptions

exception `limits.errors.``ConfigurationError`

  Bases: `Exception`

  exception raised when a configuration problem is encountered