API Reference¶
|
Rate limiting with commonly used storage backends |
|
Rate limiting strategies |
|
Implementations of storage backends to be used with |
|
Asynchronous rate limiting strategies |
|
Implementations of storage backends to be used with |
Strategies¶
Synchronous Strategies¶
The available built in rate limiting strategies which expect
a single parameter: a subclass of Storage.
Provided by limits.strategies
- class FixedWindowRateLimiter(storage: StorageTypes)[source]¶
Reference: Fixed Window
- hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Check if the rate limit can be consumed
- get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats[source]¶
Query the reset time and remaining amount for the limit
- class FixedWindowElasticExpiryRateLimiter(*args, **kwargs)[source]¶
Reference: Fixed Window with Elastic Expiry
Deprecated since version 4.1.
- hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats¶
Query the reset time and remaining amount for the limit
- test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool¶
Check if the rate limit can be consumed
- class MovingWindowRateLimiter(storage: StorageTypes)[source]¶
Reference: Moving Window
- hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Check if the rate limit can be consumed
- get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats[source]¶
returns the number of requests remaining within this limit.
- class SlidingWindowCounterRateLimiter(storage: StorageTypes)[source]¶
Reference: Sliding Window Counter
Added in version 4.1.
- hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Check if the rate limit can be consumed
- get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats[source]¶
Query the reset time and remaining amount for the limit.
All strategies implement the same abstract base class:
- class RateLimiter(storage: StorageTypes)[source]¶
- abstract hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- abstract test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Check the rate limit without consuming from it.
- abstract get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats[source]¶
Query the reset time and remaining amount for the limit
Async Strategies¶
These variants should be used in for asyncio support. These strategies
expose async variants and expect a subclass of limits.aio.storage.Storage
Provided by limits.aio.strategies
- class FixedWindowRateLimiter(storage: StorageTypes)[source]¶
Reference: Fixed Window
- async hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- async test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Check if the rate limit can be consumed
- async get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats[source]¶
Query the reset time and remaining amount for the limit
- class FixedWindowElasticExpiryRateLimiter(*args, **kwargs)[source]¶
Reference: Fixed Window with Elastic Expiry
Deprecated since version 4.1.
- async hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- Parameters:
item¶ – a
limits.limits.RateLimitIteminstanceidentifiers¶ – variable list of strings to uniquely identify the limit
cost¶ – The cost of this hit, default 1
- async get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats¶
Query the reset time and remaining amount for the limit
- async test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool¶
Check if the rate limit can be consumed
- class MovingWindowRateLimiter(storage: StorageTypes)[source]¶
Reference: Moving Window
- async hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- async test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Check if the rate limit can be consumed
- async get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats[source]¶
returns the number of requests remaining within this limit.
- class SlidingWindowCounterRateLimiter(storage: StorageTypes)[source]¶
Reference: Sliding Window Counter
Added in version 4.1.
- async hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- async test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Check if the rate limit can be consumed
- async get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats[source]¶
Query the reset time and remaining amount for the limit.
All strategies implement the same abstract base class:
- class RateLimiter(storage: StorageTypes)[source]¶
- abstract async hit(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Consume the rate limit
- abstract async test(item: RateLimitItem, *identifiers: str, cost: int = 1) bool[source]¶
Check if the rate limit can be consumed
- abstract async get_window_stats(item: RateLimitItem, *identifiers: str) WindowStats[source]¶
Query the reset time and remaining amount for the limit
Storage¶
Storage Factory function¶
Provided by limits.storage
- storage_from_string(storage_string: str, **options: float | str | bool) Storage | Storage[source]¶
Factory function to get an instance of the storage class based on the uri of the storage. In most cases using it should be sufficient instead of directly instantiating the storage classes. for example:
from limits.storage import storage_from_string memory = storage_from_string("memory://") memcached = storage_from_string("memcached://localhost:11211") redis = storage_from_string("redis://localhost:6379")
The same function can be used to construct the Async Storage variants, for example:
from limits.storage import storage_from_string memory = storage_from_string("async+memory://") memcached = storage_from_string("async+memcached://localhost:11211") redis = storage_from_string("async+redis://localhost:6379")
- Parameters:
storage_string¶ – a string of the form
scheme://host:port. More details about supported storage schemes can be found at Storage schemeoptions¶ – all remaining keyword arguments are passed to the constructor matched by
storage_string.
- Raises:
ConfigurationError – when the
storage_stringcannot be mapped to a registeredlimits.storage.Storageorlimits.aio.storage.Storageinstance.
Synchronous Storage¶
Provided by limits.storage
In-Memory Storage¶
- class MemoryStorage(uri: str | None = None, wrap_exceptions: bool = False, **_: str)[source]¶
rate limit storage using
collections.Counteras an in memory storage for fixed and elastic window strategies, and a simple list to implement moving window strategy.- Parameters:
wrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.
- STORAGE_SCHEME: list[str] | None = ['memory']¶
The storage schemes to register against this implementation
- incr(key: str, expiry: float, elastic_expiry: bool = False, amount: int = 1) int[source]¶
increments the counter for a given rate limit key
- get_moving_window(key: str, limit: int, expiry: int) tuple[float, int][source]¶
returns the starting point and the number of entries in the moving window
- acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool[source]¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
- get_sliding_window(key: str, expiry: int) tuple[int, float, int, float][source]¶
Return the previous and current window information.
- DEPENDENCIES: dict[str, Version | None] | list[str] = []¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- classmethod sliding_window_keys(key: str, expiry: int, at: float) tuple[str, str]¶
returns the previous and the current window’s keys.
- Parameters:
Returns a tuple with the previous and the current key: (previous, current).
- Example:
key = “mykey”
expiry = 60
at = 1738576292.6631825
The return value will be the tuple
("mykey/28976271", "mykey/28976270").
Redis Storage¶
- class RedisStorage(uri: str, connection_pool: redis.connection.ConnectionPool | None = None, wrap_exceptions: bool = False, **options: float | str | bool)[source]¶
Rate limit storage with redis as backend.
Depends on redis.
- Parameters:
uri¶ – uri of the form
redis://[:password]@host:port,redis://[:password]@host:port/db,rediss://[:password]@host:port,redis+unix:///path/to/socketc. This uri is passed directly toredis.from_url()except for the case ofredis+unix://where it is replaced withunix://.connection_pool¶ – if provided, the redis client is initialized with the connection pool and any other params passed as
optionswrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.options¶ – all remaining keyword arguments are passed directly to the constructor of
redis.Redis
- Raises:
ConfigurationError – when the redis library is not available
- STORAGE_SCHEME: list[str] | None = ['redis', 'rediss', 'redis+unix']¶
The storage scheme for redis
- DEPENDENCIES: dict[str, Version | None] | list[str] = {'redis': <Version('3.0')>}¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- get_moving_window(key: str, limit: int, expiry: int) tuple[float, int][source]¶
returns the starting point and the number of entries in the moving window
- get_sliding_window(key: str, expiry: int) tuple[int, float, int, float][source]¶
Return the previous and current window information.
- incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int[source]¶
increments the counter for a given rate limit key
Redis Cluster Storage¶
- class RedisClusterStorage(uri: str, wrap_exceptions: bool = False, **options: float | str | bool)[source]¶
Rate limit storage with redis cluster as backend
Depends on redis.
Changed in version 2.5.0: Cluster support was provided by the redis-py-cluster library which has been absorbed into the official redis client. By default the
redis.cluster.RedisClusterclient will be used however if the version of the package is lower than4.2.0the implementation will fallback to trying to userediscluster.RedisCluster.Changed in version 3.14.0: Dropped support for the redis-py-cluster library which has been abandoned/deprecated.
- Parameters:
uri¶ – url of the form
redis+cluster://[:password]@host:port,host:portwrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.options¶ – all remaining keyword arguments are passed directly to the constructor of
redis.cluster.RedisCluster
- Raises:
ConfigurationError – when the redis library is not available or if the redis cluster cannot be reached.
- STORAGE_SCHEME: list[str] | None = ['redis+cluster']¶
The storage scheme for redis cluster
- DEFAULT_OPTIONS: dict[str, float | str | bool] = {'max_connections': 1000}¶
Default options passed to the
RedisCluster
- DEPENDENCIES: dict[str, Version | None] | list[str] = {'redis': <Version('4.2.0')>}¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- acquire_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
- acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
Acquire an entry. Shift the current window to the previous window if it expired.
- check() bool¶
check if storage is healthy
- get_moving_window(key: str, limit: int, expiry: int) tuple[float, int]¶
returns the starting point and the number of entries in the moving window
- get_sliding_window(key: str, expiry: int) tuple[int, float, int, float]¶
Return the previous and current window information.
- incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int¶
increments the counter for a given rate limit key
- reset() int | None[source]¶
Redis Clusters are sharded and deleting across shards can’t be done atomically. Because of this, this reset loops over all keys that are prefixed with
self.PREFIXand calls delete on them, one at a time.Warning
This operation was not tested with extremely large data sets. On a large production based system, care should be taken with its usage as it could be slow on very large data sets
Redis Sentinel Storage¶
- class RedisSentinelStorage(uri: str, service_name: str | None = None, use_replicas: bool = True, sentinel_kwargs: dict[str, float | str | bool] | None = None, wrap_exceptions: bool = False, **options: float | str | bool)[source]¶
Rate limit storage with redis sentinel as backend
Depends on redis package
- Parameters:
uri¶ – url of the form
redis+sentinel://host:port,host:port/service_nameservice_name¶ – sentinel service name (if not provided in
uri)use_replicas¶ – Whether to use replicas for read only operations
sentinel_kwargs¶ – kwargs to pass as
sentinel_kwargstoredis.sentinel.Sentinelwrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.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.
- STORAGE_SCHEME: list[str] | None = ['redis+sentinel']¶
The storage scheme for redis accessed via a redis sentinel installation
- DEPENDENCIES: dict[str, Version | None] | list[str] = {'redis': <Version('3.0')>, 'redis.sentinel': <Version('3.0')>}¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- acquire_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
- acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
Acquire an entry. Shift the current window to the previous window if it expired.
- check() bool¶
check if storage is healthy
- get_moving_window(key: str, limit: int, expiry: int) tuple[float, int]¶
returns the starting point and the number of entries in the moving window
- get_sliding_window(key: str, expiry: int) tuple[int, float, int, float]¶
Return the previous and current window information.
- incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int¶
increments the counter for a given rate limit key
- reset() int | None¶
This function calls a Lua Script to delete keys prefixed with
self.PREFIXin blocks of 5000.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.
Memcached Storage¶
- class MemcachedStorage(uri: str, wrap_exceptions: bool = False, **options: str | Callable[[], MemcachedClientP])[source]¶
Rate limit storage with memcached as backend.
Depends on pymemcache.
- Parameters:
uri¶ – memcached location of the form
memcached://host:port,host:port,memcached:///var/tmp/path/to/sockwrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.options¶ – all remaining keyword arguments are passed directly to the constructor of
pymemcache.client.base.PooledClientorpymemcache.client.hash.HashClient(if there are more than one hosts specified)
- Raises:
ConfigurationError – when pymemcache is not available
- STORAGE_SCHEME: list[str] | None = ['memcached']¶
The storage scheme for memcached
- DEPENDENCIES: dict[str, Version | None] | list[str] = ['pymemcache']¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- get_client(module: ModuleType, hosts: list[tuple[str, int]], **kwargs: str) MemcachedClientP[source]¶
returns a memcached client.
- property storage: MemcachedClientP¶
lazily creates a memcached client instance using a thread local
- get_many(keys: Iterable[str]) dict[str, Any][source]¶
Return multiple counters at once
- Parameters:
keys¶ – the keys to get the counter values for
- incr(key: str, expiry: float, elastic_expiry: bool = False, amount: int = 1, set_expiration_key: bool = True) int[source]¶
increments the counter for a given rate limit key
- Parameters:
key¶ – the key to increment
expiry¶ – amount in seconds for the key to expire in
elastic_expiry¶ – whether to keep extending the rate limit window every hit.
amount¶ – the number to increment by
set_expiration_key¶ – set the expiration key with the expiration time if needed. If set to False, the key will still expire, but memcached cannot provide the expiration time.
- check() bool[source]¶
Check if storage is healthy by calling the
getcommand on the keylimiter-check
- acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool[source]¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
- get_sliding_window(key: str, expiry: int) tuple[int, float, int, float][source]¶
Return the previous and current window information.
- classmethod sliding_window_keys(key: str, expiry: int, at: float) tuple[str, str]¶
returns the previous and the current window’s keys.
- Parameters:
Returns a tuple with the previous and the current key: (previous, current).
- Example:
key = “mykey”
expiry = 60
at = 1738576292.6631825
The return value will be the tuple
("mykey/28976271", "mykey/28976270").
MongoDB Storage¶
- class MongoDBStorage(uri: str, database_name: str = 'limits', counter_collection_name: str = 'counters', window_collection_name: str = 'windows', wrap_exceptions: bool = False, **options: int | str | bool)[source]¶
Changed in version 3.14.0: Added option to select custom collection names for windows & counters
Added in version 2.1.
- Parameters:
uri¶ – uri of the form
mongodb://[user:password]@host:port?..., This uri is passed directly toMongoClientdatabase_name¶ – The database to use for storing the rate limit collections.
counter_collection_name¶ – The collection name to use for individual counters used in fixed window strategies
window_collection_name¶ – The collection name to use for sliding & moving window storage
wrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.options¶ – all remaining keyword arguments are passed to the constructor of
MongoClient
- Raises:
ConfigurationError – when the pymongo library is not available
- STORAGE_SCHEME: list[str] | None = ['mongodb', 'mongodb+srv']¶
The storage schemes to register against this implementation
- DEPENDENCIES: dict[str, Version | None] | list[str] = ['pymongo']¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- acquire_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
- acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
- check() bool¶
Check if storage is healthy by calling
pymongo.mongo_client.MongoClient.server_info()
- get_moving_window(key: str, limit: int, expiry: int) tuple[float, int]¶
returns the starting point and the number of entries in the moving window
- get_sliding_window(key: str, expiry: int) tuple[int, float, int, float]¶
Return the previous and current window information.
- incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int¶
increments the counter for a given rate limit key
- reset() int | None¶
Delete all rate limit keys in the rate limit collections (counters, windows)
Etcd Storage¶
- class EtcdStorage(uri: str, max_retries: int = 5, wrap_exceptions: bool = False, **options: str)[source]¶
Rate limit storage with etcd as backend.
Depends on etcd3.
- Parameters:
uri¶ – etcd location of the form
etcd://host:port,max_retries¶ – Maximum number of attempts to retry in the case of concurrent updates to a rate limit key
wrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.options¶ – all remaining keyword arguments are passed directly to the constructor of
etcd3.Etcd3Client
- Raises:
ConfigurationError – when etcd3 is not available
- STORAGE_SCHEME: list[str] | None = ['etcd']¶
The storage scheme for etcd
- DEPENDENCIES: dict[str, Version | None] | list[str] = ['etcd3']¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
Async Storage¶
Provided by limits.aio.storage
Async In-Memory Storage¶
- class MemoryStorage(uri: str | None = None, wrap_exceptions: bool = False, **_: str)[source]¶
rate limit storage using
collections.Counteras an in memory storage for fixed and elastic window strategies, and a simple list to implement moving window strategy.Added in version 2.1.
- Parameters:
wrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.
- STORAGE_SCHEME: list[str] | None = ['async+memory']¶
The storage scheme for in process memory storage for use in an async context
- async incr(key: str, expiry: float, elastic_expiry: bool = False, amount: int = 1) int[source]¶
increments the counter for a given rate limit key
- async decr(key: str, amount: int = 1) int[source]¶
decrements the counter for a given rate limit key. 0 is the minimum allowed value.
- Parameters:
amount¶ – the number to increment by
- async get_num_acquired(key: str, expiry: int) int[source]¶
returns the number of entries already acquired
- async get_moving_window(key: str, limit: int, expiry: int) tuple[float, int][source]¶
returns the starting point and the number of entries in the moving window
- async acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool[source]¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
- async get_sliding_window(key: str, expiry: int) tuple[int, float, int, float][source]¶
Return the previous and current window information.
- DEPENDENCIES: dict[str, Version | None] | list[str] = []¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- classmethod sliding_window_keys(key: str, expiry: int, at: float) tuple[str, str]¶
returns the previous and the current window’s keys.
- Parameters:
Returns a tuple with the previous and the current key: (previous, current).
- Example:
key = “mykey”
expiry = 60
at = 1738576292.6631825
The return value will be the tuple
("mykey/28976271", "mykey/28976270").
Async Redis Storage¶
- class RedisStorage(uri: str, wrap_exceptions: bool = False, implementation: Literal['redispy', 'coredis'] = 'coredis', **options: float | str | bool)[source]¶
Rate limit storage with redis as backend.
Changed in version 4.2: Added support for using the asyncio redis client from redis through
implementationAdded in version 2.1.
- Parameters:
uri¶ –
uri of the form:
async+redis://[:password]@host:portasync+redis://[:password]@host:port/dbasync+rediss://[:password]@host:portasync+redis+unix:///path/to/sock?db=0etc…
- This uri is passed directly to
coredis.Redis.from_url()or redis.asyncio.client.Redis.from_url()with the initialasyncremoved, except for the case ofasync+redis+unixwhere it is replaced withunix.
connection_pool¶ – if provided, the redis client is initialized with the connection pool and any other params passed as
optionswrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.implementation¶ – Whether to use the client implementation from
coredis.Redis(coredis) orredis.asyncio.client.Redis(redispy).options¶ – all remaining keyword arguments are passed directly to the constructor of
coredis.Redisorredis.asyncio.client.Redis
- Raises:
ConfigurationError – when the redis library is not available
- STORAGE_SCHEME: list[str] | None = ['async+redis', 'async+rediss', 'async+redis+unix']¶
The storage schemes for redis to be used in an async context
- DEPENDENCIES: dict[str, Version | None] | list[str] = {'coredis': <Version('3.4.0')>, 'redis': <Version('5.2.0')>}¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- async incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int[source]¶
increments the counter for a given rate limit key
- async get_moving_window(key: str, limit: int, expiry: int) tuple[float, int][source]¶
returns the starting point and the number of entries in the moving window
- async acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool[source]¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
- async get_sliding_window(key: str, expiry: int) tuple[int, float, int, float][source]¶
Return the previous and current window information.
- async reset() int | None[source]¶
This function calls a Lua Script to delete keys prefixed with
self.PREFIXin blocks of 5000.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.
Async Redis Cluster Storage¶
- class RedisClusterStorage(uri: str, wrap_exceptions: bool = False, implementation: Literal['redispy', 'coredis'] = 'coredis', **options: float | str | bool)[source]¶
Rate limit storage with redis cluster as backend
Changed in version 4.2: Added support for using the asyncio redis client from redis
Added in version 2.1.
- Parameters:
uri¶ – url of the form
async+redis+cluster://[:password]@host:port,host:portwrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.implementation¶ – Whether to use the client implementation from
coredis.RedisCluster(coredis) orredis.asyncio.cluster.RedisCluster(redispy).options¶ – all remaining keyword arguments are passed directly to the constructor of
coredis.RedisClusterorredis.asyncio.RedisCluster
- Raises:
ConfigurationError – when the redis library is not available or if the redis host cannot be pinged.
- STORAGE_SCHEME: list[str] | None = ['async+redis+cluster']¶
The storage schemes for redis cluster to be used in an async context
- async reset() int | None[source]¶
Redis Clusters are sharded and deleting across shards can’t be done atomically. Because of this, this reset loops over all keys that are prefixed with
self.PREFIXand calls delete on them, one at a time.Warning
This operation was not tested with extremely large data sets. On a large production based system, care should be taken with its usage as it could be slow on very large data sets
- DEPENDENCIES: dict[str, Version | None] | list[str] = {'coredis': <Version('3.4.0')>, 'redis': <Version('5.2.0')>}¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- async acquire_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
- async acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
- async check() bool¶
Check if storage is healthy by calling
PING
- async get_moving_window(key: str, limit: int, expiry: int) tuple[float, int]¶
returns the starting point and the number of entries in the moving window
- async get_sliding_window(key: str, expiry: int) tuple[int, float, int, float]¶
Return the previous and current window information.
Async Redis Sentinel Storage¶
- class RedisSentinelStorage(uri: str, wrap_exceptions: bool = False, implementation: Literal['redispy', 'coredis'] = 'coredis', service_name: str | None = None, use_replicas: bool = True, sentinel_kwargs: dict[str, float | str | bool] | None = None, **options: float | str | bool)[source]¶
Rate limit storage with redis sentinel as backend
Changed in version 4.2: Added support for using the asyncio redis client from redis
Added in version 2.1.
- Parameters:
uri¶ – url of the form
async+redis+sentinel://host:port,host:port/service_namewrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.implementation¶ – Whether to use the client implementation from
coredis.sentinel.Sentinel(coredis) orredis.asyncio.sentinel.Sentinel(redispy)service_name¶ – sentinel service name (if not provided in uri)
use_replicas¶ – Whether to use replicas for read only operations
sentinel_kwargs¶ – optional arguments to pass as sentinel_kwargs` to
coredis.sentinel.Sentinelorredis.asyncio.Sentineloptions¶ – all remaining keyword arguments are passed directly to the constructor of
coredis.sentinel.Sentinelorredis.asyncio.sentinel.Sentinel
- Raises:
ConfigurationError – when the redis library is not available or if the redis primary host cannot be pinged.
- STORAGE_SCHEME: list[str] | None = ['async+redis+sentinel']¶
The storage scheme for redis accessed via a redis sentinel installation
- DEPENDENCIES: dict[str, Version | None] | list[str] = {'coredis': <Version('3.4.0')>, 'coredis.sentinel': <Version('3.4.0')>, 'redis': <Version('5.2.0')>}¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- async acquire_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
- async acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
- async check() bool¶
Check if storage is healthy by calling
PING
- async get_moving_window(key: str, limit: int, expiry: int) tuple[float, int]¶
returns the starting point and the number of entries in the moving window
- async get_sliding_window(key: str, expiry: int) tuple[int, float, int, float]¶
Return the previous and current window information.
- async incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int¶
increments the counter for a given rate limit key
- async reset() int | None¶
This function calls a Lua Script to delete keys prefixed with
self.PREFIXin blocks of 5000.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.
Async Memcached Storage¶
- class MemcachedStorage(uri: str, wrap_exceptions: bool = False, **options: float | str | bool)[source]¶
Rate limit storage with memcached as backend.
Depends on emcache
Added in version 2.1.
- Parameters:
uri¶ – memcached location of the form
async+memcached://host:port,host:portwrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.options¶ – all remaining keyword arguments are passed directly to the constructor of
emcache.Client
- Raises:
ConfigurationError – when emcache is not available
- STORAGE_SCHEME: list[str] | None = ['async+memcached']¶
The storage scheme for memcached to be used in an async context
- DEPENDENCIES: dict[str, Version | None] | list[str] = ['emcache']¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- async get_many(keys: Iterable[str]) dict[bytes, ItemP][source]¶
Return multiple counters at once
- Parameters:
keys¶ – the keys to get the counter values for
- async decr(key: str, amount: int = 1, noreply: bool = False) int[source]¶
decrements the counter for a given rate limit key
retursn 0 if the key doesn’t exist or if noreply is set to True
- async incr(key: str, expiry: float, elastic_expiry: bool = False, amount: int = 1, set_expiration_key: bool = True) int[source]¶
increments the counter for a given rate limit key
- Parameters:
- async check() bool[source]¶
Check if storage is healthy by calling the
getcommand on the keylimiter-check
- async acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool[source]¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
- async get_sliding_window(key: str, expiry: int) tuple[int, float, int, float][source]¶
Return the previous and current window information.
- classmethod sliding_window_keys(key: str, expiry: int, at: float) tuple[str, str]¶
returns the previous and the current window’s keys.
- Parameters:
Returns a tuple with the previous and the current key: (previous, current).
- Example:
key = “mykey”
expiry = 60
at = 1738576292.6631825
The return value will be the tuple
("mykey/28976271", "mykey/28976270").
Async MongoDB Storage¶
- class MongoDBStorage(uri: str, database_name: str = 'limits', counter_collection_name: str = 'counters', window_collection_name: str = 'windows', wrap_exceptions: bool = False, **options: float | str | bool)[source]¶
Rate limit storage with MongoDB as backend.
Depends on motor
Changed in version 3.14.0: Added option to select custom collection names for windows & counters
Added in version 2.1.
- Parameters:
uri¶ – uri of the form
async+mongodb://[user:password]@host:port?..., This uri is passed directly toAsyncIOMotorClientdatabase_name¶ – The database to use for storing the rate limit collections.
counter_collection_name¶ – The collection name to use for individual counters used in fixed window strategies
window_collection_name¶ – The collection name to use for sliding & moving window storage
wrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.options¶ – all remaining keyword arguments are passed to the constructor of
AsyncIOMotorClient
- Raises:
ConfigurationError – when the motor or pymongo are not available
- STORAGE_SCHEME: list[str] | None = ['async+mongodb', 'async+mongodb+srv']¶
The storage scheme for MongoDB for use in an async context
- DEPENDENCIES: dict[str, Version | None] | list[str] = ['motor.motor_asyncio', 'pymongo']¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- async reset() int | None[source]¶
Delete all rate limit keys in the rate limit collections (counters, windows)
- async incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int[source]¶
increments the counter for a given rate limit key
- async check() bool[source]¶
Check if storage is healthy by calling
motor.motor_asyncio.AsyncIOMotorClient.server_info()
- async get_moving_window(key: str, limit: int, expiry: int) tuple[float, int][source]¶
returns the starting point and the number of entries in the moving window
- async acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool[source]¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
Async Etcd Storage¶
- class EtcdStorage(uri: str, max_retries: int = 5, wrap_exceptions: bool = False, **options: str)[source]¶
Rate limit storage with etcd as backend.
Depends on aetcd.
- Parameters:
uri¶ – etcd location of the form
async+etcd://host:port,max_retries¶ – Maximum number of attempts to retry in the case of concurrent updates to a rate limit key
wrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.options¶ – all remaining keyword arguments are passed directly to the constructor of
aetcd.client.Client
- Raises:
ConfigurationError – when aetcd is not available
- STORAGE_SCHEME: list[str] | None = ['async+etcd']¶
The async storage scheme for etcd
- DEPENDENCIES: dict[str, Version | None] | list[str] = ['aetcd']¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
Abstract storage classes¶
- class Storage(uri: str | None = None, wrap_exceptions: bool = False, **options: float | str | bool)[source]¶
Base class to extend when implementing a storage backend.
- Parameters:
wrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.
- STORAGE_SCHEME: list[str] | None¶
The storage schemes to register against this implementation
- abstract incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int[source]¶
increments the counter for a given rate limit key
- abstract clear(key: str) None[source]¶
resets the rate limit key
- Parameters:
key¶ – the key to clear rate limits for
- DEPENDENCIES: dict[str, Version | None] | list[str] = []¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- class MovingWindowSupport[source]¶
Abstract base class for storages that support the Moving Window strategy
- class SlidingWindowCounterSupport[source]¶
Abstract base class for storages that support the Sliding Window Counter strategy.
- abstract acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool[source]¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
Async Abstract storage classes¶
- class Storage(uri: str | None = None, wrap_exceptions: bool = False, **options: float | str | bool)[source]¶
Base class to extend when implementing an async storage backend.
Added in version 2.1.
- Parameters:
wrap_exceptions¶ – Whether to wrap storage exceptions in
limits.errors.StorageErrorbefore raising it.
- STORAGE_SCHEME: list[str] | None¶
The storage schemes to register against this implementation
- abstract async incr(key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1) int[source]¶
increments the counter for a given rate limit key
- abstract async clear(key: str) None[source]¶
resets the rate limit key
- Parameters:
key¶ – the key to clear rate limits for
- DEPENDENCIES: dict[str, Version | None] | list[str] = []¶
The python modules this class has a dependency on. Used to lazily populate the
dependencies
- class MovingWindowSupport[source]¶
Abstract base class for async storages that support the Moving Window strategy
- class SlidingWindowCounterSupport[source]¶
Abstract base class for async storages that support the Sliding Window Counter strategy
- abstract async acquire_sliding_window_entry(key: str, limit: int, expiry: int, amount: int = 1) bool[source]¶
Acquire an entry if the weighted count of the current and previous windows is less than or equal to the limit
Rate Limits¶
Provided by limits
Parsing functions¶
- parse(limit_string: str) RateLimitItem[source]¶
parses a single rate limit in string notation (e.g.
1/secondor1 per second)- Parameters:
limit_string¶ – rate limit string using Rate limit string notation
- Raises:
ValueError – if the string notation is invalid.
- parse_many(limit_string: str) list[RateLimitItem][source]¶
parses rate limits in string notation containing multiple rate limits (e.g.
1/second; 5/minute)- Parameters:
limit_string¶ – rate limit string using Rate limit string notation
- Raises:
ValueError – if the string notation is invalid.
Rate limit granularities¶
All rate limit items implement RateLimitItem by
declaring a GRANULARITY
- class RateLimitItem(amount: int, multiples: int | None = 1, namespace: str = 'LIMITER')[source]¶
defines a Rate limited resource which contains the characteristic namespace, amount and granularity multiples of the rate limiting window.
- Parameters:
amount¶ – the rate limit amount
multiples¶ – multiple of the ‘per’
GRANULARITY(e.g. ‘n’ per ‘m’ seconds)namespace¶ – category for the specific rate limit
- GRANULARITY: ClassVar[Granularity]¶
A tuple describing the granularity of this limit as (number of seconds, name)
- classmethod check_granularity_string(granularity_string: str) bool[source]¶
Checks if this instance matches a granularity_string of type
n per hour,n per minuteetc, by comparing withGRANULARITY
- key_for(*identifiers: bytes | str | int | float) str[source]¶
Constructs a key for the current limit and any additional identifiers provided.
- Parameters:
identifiers¶ – a list of strings to append to the key
- Returns:
a string key identifying this resource with each identifier separated with a ‘/’ delimiter.
- class RateLimitItemPerSecond(amount: int, multiples: int | None = 1, namespace: str = 'LIMITER')[source]¶
per second rate limited resource.
- classmethod check_granularity_string(granularity_string: str) bool¶
Checks if this instance matches a granularity_string of type
n per hour,n per minuteetc, by comparing withGRANULARITY
- get_expiry() int¶
- Returns:
the duration the limit is enforced for in seconds.
- key_for(*identifiers: bytes | str | int | float) str¶
Constructs a key for the current limit and any additional identifiers provided.
- Parameters:
identifiers¶ – a list of strings to append to the key
- Returns:
a string key identifying this resource with each identifier separated with a ‘/’ delimiter.
- GRANULARITY: ClassVar[Granularity] = (1, 'second')¶
A second
- class RateLimitItemPerMinute(amount: int, multiples: int | None = 1, namespace: str = 'LIMITER')[source]¶
per minute rate limited resource.
- classmethod check_granularity_string(granularity_string: str) bool¶
Checks if this instance matches a granularity_string of type
n per hour,n per minuteetc, by comparing withGRANULARITY
- get_expiry() int¶
- Returns:
the duration the limit is enforced for in seconds.
- key_for(*identifiers: bytes | str | int | float) str¶
Constructs a key for the current limit and any additional identifiers provided.
- Parameters:
identifiers¶ – a list of strings to append to the key
- Returns:
a string key identifying this resource with each identifier separated with a ‘/’ delimiter.
- GRANULARITY: ClassVar[Granularity] = (60, 'minute')¶
A minute
- class RateLimitItemPerHour(amount: int, multiples: int | None = 1, namespace: str = 'LIMITER')[source]¶
per hour rate limited resource.
- GRANULARITY: ClassVar[Granularity] = (3600, 'hour')¶
An hour
- classmethod check_granularity_string(granularity_string: str) bool¶
Checks if this instance matches a granularity_string of type
n per hour,n per minuteetc, by comparing withGRANULARITY
- get_expiry() int¶
- Returns:
the duration the limit is enforced for in seconds.
- key_for(*identifiers: bytes | str | int | float) str¶
Constructs a key for the current limit and any additional identifiers provided.
- Parameters:
identifiers¶ – a list of strings to append to the key
- Returns:
a string key identifying this resource with each identifier separated with a ‘/’ delimiter.
- class RateLimitItemPerDay(amount: int, multiples: int | None = 1, namespace: str = 'LIMITER')[source]¶
per day rate limited resource.
- GRANULARITY: ClassVar[Granularity] = (86400, 'day')¶
A day
- classmethod check_granularity_string(granularity_string: str) bool¶
Checks if this instance matches a granularity_string of type
n per hour,n per minuteetc, by comparing withGRANULARITY
- get_expiry() int¶
- Returns:
the duration the limit is enforced for in seconds.
- key_for(*identifiers: bytes | str | int | float) str¶
Constructs a key for the current limit and any additional identifiers provided.
- Parameters:
identifiers¶ – a list of strings to append to the key
- Returns:
a string key identifying this resource with each identifier separated with a ‘/’ delimiter.
- class RateLimitItemPerMonth(amount: int, multiples: int | None = 1, namespace: str = 'LIMITER')[source]¶
per month rate limited resource.
- GRANULARITY: ClassVar[Granularity] = (2592000, 'month')¶
A month
- classmethod check_granularity_string(granularity_string: str) bool¶
Checks if this instance matches a granularity_string of type
n per hour,n per minuteetc, by comparing withGRANULARITY
- get_expiry() int¶
- Returns:
the duration the limit is enforced for in seconds.
- key_for(*identifiers: bytes | str | int | float) str¶
Constructs a key for the current limit and any additional identifiers provided.
- Parameters:
identifiers¶ – a list of strings to append to the key
- Returns:
a string key identifying this resource with each identifier separated with a ‘/’ delimiter.
- class RateLimitItemPerYear(amount: int, multiples: int | None = 1, namespace: str = 'LIMITER')[source]¶
per year rate limited resource.
- GRANULARITY: ClassVar[Granularity] = (31104000, 'year')¶
A year
- classmethod check_granularity_string(granularity_string: str) bool¶
Checks if this instance matches a granularity_string of type
n per hour,n per minuteetc, by comparing withGRANULARITY
- get_expiry() int¶
- Returns:
the duration the limit is enforced for in seconds.
- key_for(*identifiers: bytes | str | int | float) str¶
Constructs a key for the current limit and any additional identifiers provided.
- Parameters:
identifiers¶ – a list of strings to append to the key
- Returns:
a string key identifying this resource with each identifier separated with a ‘/’ delimiter.