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