Make the usage documentation more clear

Author: tomasbasham

README.rst

@@ -37,7 +37,7 @@ To use this package you simply have to declare the decorator before the method y
 
 .. code:: python
 
-    from ratelimit import *
+    from ratelimit import rate_limited
     import requests
 
     @rate_limited(1)
@@ -49,14 +49,14 @@ To use this package you simply have to declare the decorator before the method y
 
       return response
 
-This method makes a call to our API. Note that this method has been implemented with a decorator that dictates that this method may only be called once per second.
+This method makes a call to our API. Note that this method has been implemented with a decorator enforcing that it may only be called once per second.
 
-The argument passed into the decorator imposes the time that must elapse before a method can be called again.
+The argument passed into the decorator imposes the number of method invocation allowed over a time period specified (in seconds). If no time period is specified then it default to 1 second.
 
 Contributing
 ------------
 
-1. Fork it ( https://github.com/tomasbasham/ratelimit/fork )
+1. Fork it (https://github.com/tomasbasham/ratelimit/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

ratelimit/__init__.py

@@ -1,25 +1,52 @@
+from math import floor
+
 import time
+import sys
 
-def rate_limited(period, damping = 1.0):
+def rate_limited(period = 1, every = 1.0):
   '''
   Prevent a method from being called
   if it was previously called before
   a time widows has elapsed.
 
-  :param period: The time window after which method invocations can continue.
-  :param damping: A factor by which to dampen the time window.
+  :param period: The number of method invocation allowed over a time period. Must be greater than or equal to 1.
+  :param every: A factor by which to dampen the time window (in seconds). Can be any number greater than 0.
   :return function: Decorated function that will forward method invocations if the time window has elapsed.
   '''
-  frequency = damping / float(period)
-  def decorate(func):
+  frequency = abs(every) / float(clamp(period))
+  def decorator(func):
+
+    # To get around issues with function local scope
+    # and reassigning variables, we wrap the time
+    # within a list. When updating the value we're
+    # not reassigning `last_called`, which would not
+    # work, but instead reassigning the value at a
+    # particular index.
     last_called = [0.0]
-    def func_wrapper(*args, **kargs):
+
+    def wrapper(*args, **kargs):
       elapsed = time.clock() - last_called[0]
       left_to_wait = frequency - elapsed
       if left_to_wait > 0:
         time.sleep(left_to_wait)
       ret = func(*args, **kargs)
       last_called[0] = time.clock()
       return ret
-    return func_wrapper
-  return decorate
+    return wrapper
+  return decorator
+
+def clamp(value):
+  '''
+  There must be at least 1 method invocation
+  made over the time period. Make sure the
+  value passed is at least one and it not
+  a fraction of an invocation (wtf, like???)
+
+  :param value: The number of method invocations.
+  :return int: Clamped number of invocations.
+  '''
+  return max(1, min(sys.maxsize, floor(value)))
+
+__all__ = [
+  'rate_limited'
+]

setup.py

@@ -6,7 +6,7 @@ def readme():
     return file.read()
 
 setup(name='ratelimit',
-      version=Version('1.1.0').number,
+      version=Version('1.2.0').number,
       description='API rate limit decorator',
       long_description=readme().strip(),
       author='Tomas Basham',

tests/unit/decorator_test.py

@@ -1,9 +1,20 @@
-from ratelimit import *
+from ratelimit import rate_limited
 from tests import *
 
 class TestDecorator(unittest.TestCase):
 
+  @rate_limited(1, 2)
+  def increment(self):
+    '''
+    Increment the counter at most once
+    every 2 seconds.
+    '''
+    self.count += 1
+
+  def setUp(self):
+    self.count = 0
+
   def test_decorator(self):
-    limiter = rate_limited(1)
-    decorated = limiter(lambda: 'None')
-    self.assertEqual(decorated(), 'None')
+    self.assertEqual(self.count, 0)
+    self.increment()
+    self.assertEqual(self.count, 1)