limits 4.0.1__tar.gz → 4.1__tar.gz

{limits-4.0.1 → limits-4.1}/CLASSIFIERS

@@ -5,9 +5,9 @@ Operating System :: MacOS
 Operating System :: POSIX :: Linux
 Operating System :: OS Independent
 Topic :: Software Development :: Libraries :: Python Modules
-Programming Language :: Python :: 3.8
 Programming Language :: Python :: 3.9
 Programming Language :: Python :: 3.10
 Programming Language :: Python :: 3.11
 Programming Language :: Python :: 3.12
+Programming Language :: Python :: 3.13
 Programming Language :: Python :: Implementation :: PyPy

{limits-4.0.1 → limits-4.1}/CONTRIBUTIONS.rst

@@ -5,3 +5,4 @@ Contributors
   - `Zehua Liu <https://github.com/zehua>`_
   - `David Czarnecki <https://github.com/czarneckid>`_
   - `Laurent Savaete <https://github.com/laurentS>`_
+  - `Antoine Merino <https://github.com/merinorus>`_

{limits-4.0.1 → limits-4.1}/HISTORY.rst

@@ -3,6 +3,22 @@
 Changelog
 =========
 
+v4.1
+----
+Release Date: 2025-03-07
+
+  * Feature
+
+    * Add new Sliding Window Counter strategy
+
+  * Deprecation
+
+    * Deprecate the Fixed window with elastic expiry strategy
+
+  * Documentation
+
+    * Re-write strategy documentation with concrete examples
+
 v4.0.1
 ------
 Release Date: 2025-01-16
@@ -765,5 +781,6 @@ Release Date: 2015-01-08
 
 
 
+
 
 

limits-4.1/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.2
+Name: limits
+Version: 4.1
+Summary: Rate limiting utilities
+Home-page: https://limits.readthedocs.org
+Author: Ali-Akber Saifee
+Author-email: ali@indydevs.org
+License: MIT
+Project-URL: Source, https://github.com/alisaifee/limits
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.9
+License-File: LICENSE.txt
+Requires-Dist: deprecated>=1.2
+Requires-Dist: packaging<25,>=21
+Requires-Dist: typing_extensions
+Provides-Extra: redis
+Requires-Dist: redis!=4.5.2,!=4.5.3,<6.0.0,>3; extra == "redis"
+Provides-Extra: rediscluster
+Requires-Dist: redis!=4.5.2,!=4.5.3,>=4.2.0; extra == "rediscluster"
+Provides-Extra: memcached
+Requires-Dist: pymemcache<5.0.0,>3; extra == "memcached"
+Provides-Extra: mongodb
+Requires-Dist: pymongo<5,>4.1; extra == "mongodb"
+Provides-Extra: etcd
+Requires-Dist: etcd3; extra == "etcd"
+Provides-Extra: async-redis
+Requires-Dist: coredis<5,>=3.4.0; extra == "async-redis"
+Provides-Extra: async-memcached
+Requires-Dist: emcache>=0.6.1; python_version < "3.11" and extra == "async-memcached"
+Requires-Dist: emcache>=1; (python_version >= "3.11" and python_version < "3.13.0") and extra == "async-memcached"
+Provides-Extra: async-mongodb
+Requires-Dist: motor<4,>=3; extra == "async-mongodb"
+Provides-Extra: async-etcd
+Requires-Dist: aetcd; extra == "async-etcd"
+Provides-Extra: all
+Requires-Dist: redis!=4.5.2,!=4.5.3,<6.0.0,>3; extra == "all"
+Requires-Dist: redis!=4.5.2,!=4.5.3,>=4.2.0; extra == "all"
+Requires-Dist: pymemcache<5.0.0,>3; extra == "all"
+Requires-Dist: pymongo<5,>4.1; extra == "all"
+Requires-Dist: etcd3; extra == "all"
+Requires-Dist: coredis<5,>=3.4.0; extra == "all"
+Requires-Dist: emcache>=0.6.1; python_version < "3.11" and extra == "all"
+Requires-Dist: emcache>=1; (python_version >= "3.11" and python_version < "3.13.0") and extra == "all"
+Requires-Dist: motor<4,>=3; extra == "all"
+Requires-Dist: aetcd; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: license
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+.. |ci| image:: https://github.com/alisaifee/limits/actions/workflows/main.yml/badge.svg?branch=master
+    :target: https://github.com/alisaifee/limits/actions?query=branch%3Amaster+workflow%3ACI
+.. |codecov| image:: https://codecov.io/gh/alisaifee/limits/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/alisaifee/limits
+.. |pypi| image:: https://img.shields.io/pypi/v/limits.svg?style=flat-square
+    :target: https://pypi.python.org/pypi/limits
+.. |pypi-versions| image:: https://img.shields.io/pypi/pyversions/limits?style=flat-square
+    :target: https://pypi.python.org/pypi/limits
+.. |license| image:: https://img.shields.io/pypi/l/limits.svg?style=flat-square
+    :target: https://pypi.python.org/pypi/limits
+.. |docs| image:: https://readthedocs.org/projects/limits/badge/?version=latest
+   :target: https://limits.readthedocs.org
+
+limits
+------
+|docs| |ci| |codecov| |pypi| |pypi-versions| |license|
+
+
+**limits** is a python library for rate limiting via multiple strategies
+with commonly used storage backends (Redis, Memcached, MongoDB & Etcd).
+
+The library provides identical APIs for use in sync and
+`async <https://limits.readthedocs.io/en/stable/async.html>`_ codebases.
+
+
+Supported Strategies
+====================
+
+All strategies support the follow methods:
+
+- `hit <https://limits.readthedocs.io/en/stable/api.html#limits.strategies.RateLimiter.hit>`_: consume a request.
+- `test <https://limits.readthedocs.io/en/stable/api.html#limits.strategies.RateLimiter.test>`_: check if a request is allowed.
+- `get_window_stats <https://limits.readthedocs.io/en/stable/api.html#limits.strategies.RateLimiter.get_window_stats>`_: retrieve remaining quota and reset time.
+
+Fixed Window
+------------
+`Fixed Window <https://limits.readthedocs.io/en/latest/strategies.html#fixed-window>`_
+
+This strategy is the most memory‑efficient because it uses a single counter per resource and
+rate limit. When the first request arrives, a window is started for a fixed duration
+(e.g., for a rate limit of 10 requests per minute the window expires in 60 seconds from the first request).
+All requests in that window increment the counter and when the window expires, the counter resets.
+
+Burst traffic that bypasses the rate limit may occur at window boundaries.
+
+For example, with a rate limit of 10 requests per minute:
+
+- At **00:00:45**, the first request arrives, starting a window from **00:00:45** to **00:01:45**.
+- All requests between **00:00:45** and **00:01:45** count toward the limit.
+- If 10 requests occur at any time in that window, any further request before **00:01:45** is rejected.
+- At **00:01:45**, the counter resets and a new window starts which would allow 10 requests
+  until **00:02:45**.
+
+Moving Window
+-------------
+`Moving Window <https://limits.readthedocs.io/en/latest/strategies.html#moving-window>`_
+
+This strategy adds each request’s timestamp to a log if the ``nth`` oldest entry (where ``n``
+is the limit) is either not present or is older than the duration of the window (for example with a rate limit of
+``10 requests per minute`` if there are either less than 10 entries or the 10th oldest entry is atleast
+60 seconds old). Upon adding a new entry to the log "expired" entries are truncated.
+
+For example, with a rate limit of 10 requests per minute:
+
+- At **00:00:10**, a client sends 1 requests which are allowed.
+- At **00:00:20**, a client sends 2 requests which are allowed.
+- At **00:00:30**, the client sends 4 requests which are allowed.
+- At **00:00:50**, the client sends 3 requests which are allowed (total = 10).
+- At **00:01:11**, the client sends 1 request. The strategy checks the timestamp of the
+  10th oldest entry (**00:00:10**) which is now 61 seconds old and thus expired. The request
+  is allowed.
+- At **00:01:12**, the client sends 1 request. The 10th oldest entry's timestamp is **00:00:20**
+  which is only 52 seconds old. The request is rejected.
+
+Sliding Window Counter
+------------------------
+`Sliding Window Counter <https://limits.readthedocs.io/en/latest/strategies.html#sliding-window-counter>`_
+
+This strategy approximates the moving window while using less memory by maintaining
+two counters:
+
+- **Current bucket:** counts requests in the ongoing period.
+- **Previous bucket:** counts requests in the immediately preceding period.
+
+When a request arrives, the effective request count is calculated as::
+
+    weighted_count = current_count + floor(previous_count * weight)
+
+The weight is based on how much time has elapsed in the current bucket::
+
+    weight = (bucket_duration - elapsed_time) / bucket_duration
+
+If ``weighted_count`` is below the limit, the request is allowed.
+
+For example, with a rate limit of 10 requests per minute:
+
+Assume:
+
+- The current bucket (spanning **00:01:00** to **00:02:00**) has 8 hits.
+- The previous bucket (spanning **00:00:00** to **00:01:00**) has 4 hits.
+
+Scenario 1:
+
+- A new request arrives at **00:01:30**, 30 seconds into the current bucket.
+- ``weight = (60 - 30) / 60 = 0.5``.
+- ``weighted_count = floor(8 + (4 * 0.5)) = floor(8 + 2) = 10``.
+- Since the weighted count equals the limit, the request is rejected.
+
+Scenario 2:
+
+- A new request arrives at **00:01:40**, 40 seconds into the current bucket.
+- ``weight = (60 - 40) / 60 ≈ 0.33``.
+- ``weighted_count = floor(8 + (4 * 0.33)) = floor(8 + 1.32) = 9``.
+- Since the weighted count is below the limit, the request is allowed.
+
+Storage backends
+================
+
+- `Redis <https://limits.readthedocs.io/en/latest/storage.html#redis-storage>`_
+- `Memcached <https://limits.readthedocs.io/en/latest/storage.html#memcached-storage>`_
+- `MongoDB <https://limits.readthedocs.io/en/latest/storage.html#mongodb-storage>`_
+- `Etcd <https://limits.readthedocs.io/en/latest/storage.html#etcd-storage>`_
+- `In-Memory <https://limits.readthedocs.io/en/latest/storage.html#in-memory-storage>`_
+
+Dive right in
+=============
+
+Initialize the storage backend
+
+.. code-block:: python
+
+   from limits import storage
+   backend = storage.MemoryStorage()
+   # or memcached
+   backend = storage.MemcachedStorage("memcached://localhost:11211")
+   # or redis
+   backend = storage.RedisStorage("redis://localhost:6379")
+   # or mongodb
+   backend = storage.MongoDbStorage("mongodb://localhost:27017")
+   # or use the factory
+   storage_uri = "memcached://localhost:11211"
+   backend = storage.storage_from_string(storage_uri)
+
+Initialize a rate limiter with a strategy
+
+.. code-block:: python
+
+   from limits import strategies
+   strategy = strategies.MovingWindowRateLimiter(backend)
+   # or fixed window
+   strategy = strategies.FixedWindowRateLimiter(backend)
+   # or sliding window
+   strategy = strategies.SlidingWindowCounterRateLimiter(backend)
+
+
+Initialize a rate limit
+
+.. code-block:: python
+
+    from limits import parse
+    one_per_minute = parse("1/minute")
+
+Initialize a rate limit explicitly
+
+.. code-block:: python
+
+    from limits import RateLimitItemPerSecond
+    one_per_second = RateLimitItemPerSecond(1, 1)
+
+Test the limits
+
+.. code-block:: python
+
+    import time
+    assert True == strategy.hit(one_per_minute, "test_namespace", "foo")
+    assert False == strategy.hit(one_per_minute, "test_namespace", "foo")
+    assert True == strategy.hit(one_per_minute, "test_namespace", "bar")
+
+    assert True == strategy.hit(one_per_second, "test_namespace", "foo")
+    assert False == strategy.hit(one_per_second, "test_namespace", "foo")
+    time.sleep(1)
+    assert True == strategy.hit(one_per_second, "test_namespace", "foo")
+
+Check specific limits without hitting them
+
+.. code-block:: python
+
+    assert True == strategy.hit(one_per_second, "test_namespace", "foo")
+    while not strategy.test(one_per_second, "test_namespace", "foo"):
+        time.sleep(0.01)
+    assert True == strategy.hit(one_per_second, "test_namespace", "foo")
+
+Query available capacity and reset time for a limit
+
+.. code-block:: python
+
+   assert True == strategy.hit(one_per_minute, "test_namespace", "foo")
+   window = strategy.get_window_stats(one_per_minute, "test_namespace", "foo")
+   assert window.remaining == 0
+   assert False == strategy.hit(one_per_minute, "test_namespace", "foo")
+   time.sleep(window.reset_time - time.time())
+   assert True == strategy.hit(one_per_minute, "test_namespace", "foo")
+
+
+Links
+=====
+
+* `Documentation <http://limits.readthedocs.org/en/latest>`_
+* `Changelog <http://limits.readthedocs.org/en/stable/changelog.html>`_
+

limits-4.1/README.rst

@@ -0,0 +1,210 @@
+.. |ci| image:: https://github.com/alisaifee/limits/actions/workflows/main.yml/badge.svg?branch=master
+    :target: https://github.com/alisaifee/limits/actions?query=branch%3Amaster+workflow%3ACI
+.. |codecov| image:: https://codecov.io/gh/alisaifee/limits/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/alisaifee/limits
+.. |pypi| image:: https://img.shields.io/pypi/v/limits.svg?style=flat-square
+    :target: https://pypi.python.org/pypi/limits
+.. |pypi-versions| image:: https://img.shields.io/pypi/pyversions/limits?style=flat-square
+    :target: https://pypi.python.org/pypi/limits
+.. |license| image:: https://img.shields.io/pypi/l/limits.svg?style=flat-square
+    :target: https://pypi.python.org/pypi/limits
+.. |docs| image:: https://readthedocs.org/projects/limits/badge/?version=latest
+   :target: https://limits.readthedocs.org
+
+limits
+------
+|docs| |ci| |codecov| |pypi| |pypi-versions| |license|
+
+
+**limits** is a python library for rate limiting via multiple strategies
+with commonly used storage backends (Redis, Memcached, MongoDB & Etcd).
+
+The library provides identical APIs for use in sync and
+`async <https://limits.readthedocs.io/en/stable/async.html>`_ codebases.
+
+
+Supported Strategies
+====================
+
+All strategies support the follow methods:
+
+- `hit <https://limits.readthedocs.io/en/stable/api.html#limits.strategies.RateLimiter.hit>`_: consume a request.
+- `test <https://limits.readthedocs.io/en/stable/api.html#limits.strategies.RateLimiter.test>`_: check if a request is allowed.
+- `get_window_stats <https://limits.readthedocs.io/en/stable/api.html#limits.strategies.RateLimiter.get_window_stats>`_: retrieve remaining quota and reset time.
+
+Fixed Window
+------------
+`Fixed Window <https://limits.readthedocs.io/en/latest/strategies.html#fixed-window>`_
+
+This strategy is the most memory‑efficient because it uses a single counter per resource and
+rate limit. When the first request arrives, a window is started for a fixed duration
+(e.g., for a rate limit of 10 requests per minute the window expires in 60 seconds from the first request).
+All requests in that window increment the counter and when the window expires, the counter resets.
+
+Burst traffic that bypasses the rate limit may occur at window boundaries.
+
+For example, with a rate limit of 10 requests per minute:
+
+- At **00:00:45**, the first request arrives, starting a window from **00:00:45** to **00:01:45**.
+- All requests between **00:00:45** and **00:01:45** count toward the limit.
+- If 10 requests occur at any time in that window, any further request before **00:01:45** is rejected.
+- At **00:01:45**, the counter resets and a new window starts which would allow 10 requests
+  until **00:02:45**.
+
+Moving Window
+-------------
+`Moving Window <https://limits.readthedocs.io/en/latest/strategies.html#moving-window>`_
+
+This strategy adds each request’s timestamp to a log if the ``nth`` oldest entry (where ``n``
+is the limit) is either not present or is older than the duration of the window (for example with a rate limit of
+``10 requests per minute`` if there are either less than 10 entries or the 10th oldest entry is atleast
+60 seconds old). Upon adding a new entry to the log "expired" entries are truncated.
+
+For example, with a rate limit of 10 requests per minute:
+
+- At **00:00:10**, a client sends 1 requests which are allowed.
+- At **00:00:20**, a client sends 2 requests which are allowed.
+- At **00:00:30**, the client sends 4 requests which are allowed.
+- At **00:00:50**, the client sends 3 requests which are allowed (total = 10).
+- At **00:01:11**, the client sends 1 request. The strategy checks the timestamp of the
+  10th oldest entry (**00:00:10**) which is now 61 seconds old and thus expired. The request
+  is allowed.
+- At **00:01:12**, the client sends 1 request. The 10th oldest entry's timestamp is **00:00:20**
+  which is only 52 seconds old. The request is rejected.
+
+Sliding Window Counter
+------------------------
+`Sliding Window Counter <https://limits.readthedocs.io/en/latest/strategies.html#sliding-window-counter>`_
+
+This strategy approximates the moving window while using less memory by maintaining
+two counters:
+
+- **Current bucket:** counts requests in the ongoing period.
+- **Previous bucket:** counts requests in the immediately preceding period.
+
+When a request arrives, the effective request count is calculated as::
+
+    weighted_count = current_count + floor(previous_count * weight)
+
+The weight is based on how much time has elapsed in the current bucket::
+
+    weight = (bucket_duration - elapsed_time) / bucket_duration
+
+If ``weighted_count`` is below the limit, the request is allowed.
+
+For example, with a rate limit of 10 requests per minute:
+
+Assume:
+
+- The current bucket (spanning **00:01:00** to **00:02:00**) has 8 hits.
+- The previous bucket (spanning **00:00:00** to **00:01:00**) has 4 hits.
+
+Scenario 1:
+
+- A new request arrives at **00:01:30**, 30 seconds into the current bucket.
+- ``weight = (60 - 30) / 60 = 0.5``.
+- ``weighted_count = floor(8 + (4 * 0.5)) = floor(8 + 2) = 10``.
+- Since the weighted count equals the limit, the request is rejected.
+
+Scenario 2:
+
+- A new request arrives at **00:01:40**, 40 seconds into the current bucket.
+- ``weight = (60 - 40) / 60 ≈ 0.33``.
+- ``weighted_count = floor(8 + (4 * 0.33)) = floor(8 + 1.32) = 9``.
+- Since the weighted count is below the limit, the request is allowed.
+
+Storage backends
+================
+
+- `Redis <https://limits.readthedocs.io/en/latest/storage.html#redis-storage>`_
+- `Memcached <https://limits.readthedocs.io/en/latest/storage.html#memcached-storage>`_
+- `MongoDB <https://limits.readthedocs.io/en/latest/storage.html#mongodb-storage>`_
+- `Etcd <https://limits.readthedocs.io/en/latest/storage.html#etcd-storage>`_
+- `In-Memory <https://limits.readthedocs.io/en/latest/storage.html#in-memory-storage>`_
+
+Dive right in
+=============
+
+Initialize the storage backend
+
+.. code-block:: python
+
+   from limits import storage
+   backend = storage.MemoryStorage()
+   # or memcached
+   backend = storage.MemcachedStorage("memcached://localhost:11211")
+   # or redis
+   backend = storage.RedisStorage("redis://localhost:6379")
+   # or mongodb
+   backend = storage.MongoDbStorage("mongodb://localhost:27017")
+   # or use the factory
+   storage_uri = "memcached://localhost:11211"
+   backend = storage.storage_from_string(storage_uri)
+
+Initialize a rate limiter with a strategy
+
+.. code-block:: python
+
+   from limits import strategies
+   strategy = strategies.MovingWindowRateLimiter(backend)
+   # or fixed window
+   strategy = strategies.FixedWindowRateLimiter(backend)
+   # or sliding window
+   strategy = strategies.SlidingWindowCounterRateLimiter(backend)
+
+
+Initialize a rate limit
+
+.. code-block:: python
+
+    from limits import parse
+    one_per_minute = parse("1/minute")
+
+Initialize a rate limit explicitly
+
+.. code-block:: python
+
+    from limits import RateLimitItemPerSecond
+    one_per_second = RateLimitItemPerSecond(1, 1)
+
+Test the limits
+
+.. code-block:: python
+
+    import time
+    assert True == strategy.hit(one_per_minute, "test_namespace", "foo")
+    assert False == strategy.hit(one_per_minute, "test_namespace", "foo")
+    assert True == strategy.hit(one_per_minute, "test_namespace", "bar")
+
+    assert True == strategy.hit(one_per_second, "test_namespace", "foo")
+    assert False == strategy.hit(one_per_second, "test_namespace", "foo")
+    time.sleep(1)
+    assert True == strategy.hit(one_per_second, "test_namespace", "foo")
+
+Check specific limits without hitting them
+
+.. code-block:: python
+
+    assert True == strategy.hit(one_per_second, "test_namespace", "foo")
+    while not strategy.test(one_per_second, "test_namespace", "foo"):
+        time.sleep(0.01)
+    assert True == strategy.hit(one_per_second, "test_namespace", "foo")
+
+Query available capacity and reset time for a limit
+
+.. code-block:: python
+
+   assert True == strategy.hit(one_per_minute, "test_namespace", "foo")
+   window = strategy.get_window_stats(one_per_minute, "test_namespace", "foo")
+   assert window.remaining == 0
+   assert False == strategy.hit(one_per_minute, "test_namespace", "foo")
+   time.sleep(window.reset_time - time.time())
+   assert True == strategy.hit(one_per_minute, "test_namespace", "foo")
+
+
+Links
+=====
+
+* `Documentation <http://limits.readthedocs.org/en/latest>`_
+* `Changelog <http://limits.readthedocs.org/en/stable/changelog.html>`_
+

{limits-4.0.1 → limits-4.1}/doc/source/api.rst

@@ -30,6 +30,7 @@ Provided by :mod:`limits.strategies`
 .. autoclass:: FixedWindowRateLimiter
 .. autoclass:: FixedWindowElasticExpiryRateLimiter
 .. autoclass:: MovingWindowRateLimiter
+.. autoclass:: SlidingWindowCounterRateLimiter
 
 All strategies implement the same abstract base class:
 
@@ -48,6 +49,7 @@ Provided by :mod:`limits.aio.strategies`
 .. autoclass:: FixedWindowRateLimiter
 .. autoclass:: FixedWindowElasticExpiryRateLimiter
 .. autoclass:: MovingWindowRateLimiter
+.. autoclass:: SlidingWindowCounterRateLimiter
 
 All strategies implement the same abstract base class:
 
@@ -152,13 +154,15 @@ Abstract storage classes
 
 .. autoclass:: limits.storage.Storage
 .. autoclass:: limits.storage.MovingWindowSupport
+.. autoclass:: limits.storage.SlidingWindowCounterSupport
 
 
-Async variants
-^^^^^^^^^^^^^^
+Async Abstract storage classes
+--------------------------------
 
 .. autoclass:: limits.aio.storage.Storage
 .. autoclass:: limits.aio.storage.MovingWindowSupport
+.. autoclass:: limits.aio.storage.SlidingWindowCounterSupport
 
 
 Rate Limits

{limits-4.0.1 → limits-4.1}/doc/source/conf.py

@@ -47,6 +47,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinx.ext.mathjax",
     "sphinxext.opengraph",
     "sphinxcontrib.programoutput",
     "sphinx_copybutton",