API

Storage

Abstract storage class

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

Base class to extend when implementing a storage backend.

Backend Implementations

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

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.

class limits.storage.RedisStorage(uri, **options)

Rate limit storage with redis as backend.

Depends on the redis-py library.

Parameters

• uri (str) – uri of the form redis://[:password]@host:port, redis://[:password]@host:port/db, rediss://[:password]@host:port, redis+unix:///path/to/sock etc. This uri is passed directly to redis.from_url() except for the case of redis+unix where it is replaced with unix.

• **options – all remaining keyword arguments are passed directly to the constructor of redis.Redis

Raises

ConfigurationError – when the redis library is not available

class limits.storage.RedisClusterStorage(uri, **options)

Rate limit storage with redis cluster as backend

Depends on redis-py-cluster library

Parameters

• uri (str) – url of the form redis+cluster://[:password]@host:port,host:port

• **options – all remaining keyword arguments are passed directly to the constructor of rediscluster.RedisCluster

Raises

ConfigurationError – when the rediscluster library is not available or if the redis host cannot be pinged.

class limits.storage.RedisSentinelStorage(uri, service_name=None, **options)

Rate limit storage with redis sentinel as backend

Depends on redis-py library

Parameters

• uri (str) – url of the form redis+sentinel://host:port,host:port/service_name

• service_name, optional (str) – sentinel service name (if not provided in uri)

• **options – all remaining keyword arguments are passed directly to the constructor of redis.sentinel.Sentinel

Raises

ConfigurationError – when the redis library is not available or if the redis master host cannot be pinged.

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

Rate limit storage with memcached as backend.

Depends on the pymemcache library.

Parameters

• uri (str) – memcached location of the form memcached://host:port,host:port, memcached:///var/tmp/path/to/sock

• **options – all remaining keyword arguments are passed directly to the constructor of pymemcache.client.base.Client

Raises

ConfigurationError – when pymemcache is not available or memcached location cannot be parsed.

class limits.storage.GAEMemcachedStorage(uri, **options)

rate limit storage with GAE memcache as backend

Parameters

• uri (str) – memcached location of the form memcached://host:port,host:port, memcached:///var/tmp/path/to/sock

• **options – all remaining keyword arguments are passed directly to the constructor of pymemcache.client.base.Client

Raises

ConfigurationError – when pymemcache is not available or memcached location cannot be parsed.

Utility Methods

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)

class limits.strategies.FixedWindowRateLimiter(storage)

Reference: Fixed Window

class limits.strategies.FixedWindowElasticExpiryRateLimiter(storage)

Reference: Fixed Window with Elastic Expiry

class limits.strategies.MovingWindowRateLimiter(storage)

Reference: Moving Window

Rate Limits

Rate limit granularities

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

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

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

per year rate limited resource.

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

per month rate limited resource.

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

per day rate limited resource.

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

per hour rate limited resource.

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

per minute rate limited resource.

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

per second rate limited resource.

Utility Methods

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

exception raised when a configuration problem is encountered