Package: rrl
rrl - Redis Rate LimitingVery simple reusable redis-backed rate limiting code.  Designed for OpenStates.org.Configurationrrl, as the name implies, requires aRedisserver.rrlis entirely configured by environment variables:RRL_REDIS_HOST- hostname of Redis instance (default:localhost)RRL_REDIS_PORT- port of Redis instance (default:6379)RRL_REDIS_DB- database ID to use for RRL (default:0)UsageUsage can be throttled on a per-minute, per-hour, and/or per-day basis.rrlhas the concept of aTierwhich associates a name with a set of limitations, for instance:# create two tiers
bronze = Tier(name="bronze", per_minute=1, per_hour=0, per_day=500)
silver = Tier(name="silver", per_minute=5, per_hour=0, per_day=4000)These tiers do not use the per_hour feature, but will limit users to 1 or 5 requests per minute respectively.  There's also a daily limit at 500 or 4000 requests per day.Then you'll need an instance ofrrl.RateLimiter, which will be instantiated with these tiers:limiter = RateLimiter(tiers=[bronze, silver])Then to apply limiting, you'll call thecheck_limitfunction, which takes three parameters:key- A unique-per user key, often the user's API key or username. (Note:rrldoes not know if a key is valid or not, that validation should be in your application and usually occur before the call tocheck_limit.)tier_name- The name of one of the tiers as specified when instantiating theRateLimiterclass.  (Note:rrldoes not have a concept of which users are in which tier, that logic should be handled by your key validation code.)Example call:limiter.check_limit(key="1234", tier_name="bronze")This call will return without any error if the call is deemed allowed.If any of the rate limits are exceeded it will instead raise aRateLimitExceededexception describing which limit was exceeded.If multiple limits were exceeded it will return the shortest limit violated.Advanced UsageObtaining Usage InformationYourRateLimiterinstance also has a method namedget_usage_since, which takes four parameters:key- Which key you're requesting usage information for.start- Date that you'd like usage since, as adatetime.dateobject.end- Optional end date if you'd only like usage within a certain window, otherwise the current day is used.This will return a list ofDailyUsagedataclasses with the following attributes:date-datetime.datecalls- Number of calls made on that date.This method can be useful for showing users an overview of their data.Advanced ConfigurationWhen instantiating aRateLimiterthere are several keyword-only parameters you may set:prefixPassing a prefix like:limiter = RateLimiter(tiers, prefix="v1")will scope all calls to limiter to a given prefix, this can be useful if you want multiple limiters but want to ensure that they do not interfere with one another.use_redis_timeTrueby default, but if you set toFalsethe application's system time will be used instead.The tradeoff here is one fewer call to Redis per call tocheck_limit, but if your machines experience any clock drift unexpected results may occur.track_daily_usageTrueby default, but if set toFalse,rrlwill not store the necessary information to makeget_usage_sincework.  This results in a slight overhead reduction, but the usage information will not be stored in Redis and will be impossible to retrieve.