API reference

Limiter class

class slowapi.extension.Limiter(key_func, default_limits=[], application_limits=[], headers_enabled=False, strategy=None, storage_uri=None, storage_options={}, auto_check=True, swallow_errors=False, in_memory_fallback=[], in_memory_fallback_enabled=False, retry_after=None, key_prefix='', enabled=True, config_filename=None)

Initializes the slowapi rate limiter.

parameter

  • app: Starlette/FastAPI instance to initialize the extension with.

  • default_limits: a variable list of strings or callables returning strings denoting global limits to apply to all routes. ratelimit-string for more details.

  • application_limits: a variable list of strings or callables returning strings for limits that are applied to the entire application (i.e a shared limit for all routes)

  • key_func: a callable that returns the domain to rate limit by.

  • headers_enabled: whether X-RateLimit response headers are written.

  • strategy: the strategy to use. refer to ratelimit-strategy

  • storage_uri: the storage location. refer to ratelimit-conf

  • storage_options: kwargs to pass to the storage implementation upon instantiation.

  • auto_check: whether to automatically check the rate limit in the before_request chain of the application. default True
  • swallow_errors: whether to swallow errors when hitting a rate limit. An exception will still be logged. default False
  • in_memory_fallback: a variable list of strings or callables returning strings denoting fallback limits to apply when the storage is down.
  • in_memory_fallback_enabled: simply falls back to in memory storage when the main storage is down and inherits the original limits.
  • key_prefix: prefix prepended to rate limiter keys.
  • enabled: set to False to deactivate the limiter (default: True)
  • config_filename: name of the config file for Starlette from which to load settings for the rate limiter. Defaults to ".env".
limit(self, limit_value, key_func=None, per_method=False, methods=None, error_message=None, exempt_when=None, override_defaults=True)

Decorator to be used for rate limiting individual routes.

  • limit_value: rate limit string or a callable that returns a string. :ref:ratelimit-string for more details.
  • key_func: function/lambda to extract the unique identifier for the rate limit. defaults to remote address of the request.
  • per_method: whether the limit is sub categorized into the http method of the request.
  • methods: if specified, only the methods in this list will be rate limited (default: None).
  • error_message: string (or callable that returns one) to override the error message used in the response.
  • exempt_when: function returning a boolean indicating whether to exempt the route from the limit
  • override_defaults: whether to override the default limits (default: True)
shared_limit(self, limit_value, scope, key_func=None, error_message=None, exempt_when=None, override_defaults=True)

Decorator to be applied to multiple routes sharing the same rate limit.

  • limit_value: rate limit string or a callable that returns a string. :ref:ratelimit-string for more details.
  • scope: a string or callable that returns a string for defining the rate limiting scope.
  • key_func: function/lambda to extract the unique identifier for the rate limit. defaults to remote address of the request.
  • per_method: whether the limit is sub categorized into the http method of the request.
  • methods: if specified, only the methods in this list will be rate limited (default: None).
  • error_message: string (or callable that returns one) to override the error message used in the response.
  • exempt_when: function returning a boolean indicating whether to exempt the route from the limit
  • override_defaults: whether to override the default limits (default: True)

Wrappers around Limit objects

These wrap the RateLimitItem from alisaifee/limits.

class slowapi.wrappers.Limit(limit, key_func, scope, per_method, methods, error_message, exempt_when, override_defaults)

simple wrapper to encapsulate limits and their context

class slowapi.wrappers.LimitGroup(limit_provider, key_function, scope, per_method, methods, error_message, exempt_when, override_defaults)

represents a group of related limits either from a string or a callable that returns one

Utility functions

slowapi.util.get_ipaddr(request)

Returns the ip address for the current request (or 127.0.0.1 if none found) based on the X-Forwarded-For headers. Note that a more robust method for determining IP address of the client is provided by uvicorn's ProxyHeadersMiddleware.

slowapi.util.get_remote_address(request)

Returns the ip address for the current request (or 127.0.0.1 if none found)