From 4679a3494c0d1009085c8d791c433398de12e0c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krist=C3=B3f=20T=C3=B3th?= Date: Tue, 31 Jul 2018 05:19:15 +0200 Subject: [PATCH] Add docstrings to RateLimiter --- lib/tfw/decorators/rate_limiter.py | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/lib/tfw/decorators/rate_limiter.py b/lib/tfw/decorators/rate_limiter.py index fdfa992..e0c87d1 100644 --- a/lib/tfw/decorators/rate_limiter.py +++ b/lib/tfw/decorators/rate_limiter.py @@ -7,8 +7,32 @@ from time import time, sleep from tfw.decorators.lazy_property import lazy_property +# TODO: add this to sphinx docs class RateLimiter: + """ + Decorator class for rate limiting. + + When applied to a function this decorator will apply rate limiting + if the function is invoked more frequently than rate_per_seconds. + + By default rate limiting means sleeping until the next invocation time + as per __init__ parameter rate_per_seconds. + + Note that this decorator BLOCKS THE THREAD it is being executed on, + so it is only acceptable for stuff running on a separate thread. + + If this is no good for you please refer to AsyncRateLimiter in this module, + which is designed not to block and use the IOLoop it is being called from, + or redefine the action argument of __init__ (which defaults to time.sleep). + """ def __init__(self, rate_per_second, action=sleep): + """ + :param rate_per_second: max frequency the decorated method should be + invoked with + :param action: what to do when rate limiting. defaults to time.sleep, + receives the number of seconds until the next invocation + should occour as an argument + """ self.min_interval = 1 / float(rate_per_second) self.action = action self.fun = None