{"author":"Ali-Akber Saifee","author_email":"ali@indydevs.org","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","License :: OSI Approved :: MIT License","Operating System :: MacOS","Operating System :: OS Independent","Operating System :: POSIX :: Linux","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","Topic :: Software Development :: Libraries :: Python Modules"],"description":".. |ci| image:: https://github.com/alisaifee/limits/actions/workflows/main.yml/badge.svg?branch=master\n :target: https://github.com/alisaifee/limits/actions?query=branch%3Amaster+workflow%3ACI\n.. |codecov| image:: https://codecov.io/gh/alisaifee/limits/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/alisaifee/limits\n.. |pypi| image:: https://img.shields.io/pypi/v/limits.svg?style=flat-square\n :target: https://pypi.python.org/pypi/limits\n.. |pypi-versions| image:: https://img.shields.io/pypi/pyversions/limits?style=flat-square\n :target: https://pypi.python.org/pypi/limits\n.. |license| image:: https://img.shields.io/pypi/l/limits.svg?style=flat-square\n :target: https://pypi.python.org/pypi/limits\n.. |docs| image:: https://readthedocs.org/projects/limits/badge/?version=latest\n :target: https://limits.readthedocs.org\n\n######\nlimits\n######\n|docs| |ci| |codecov| |pypi| |pypi-versions| |license|\n\n\n**limits** is a python library for rate limiting via multiple strategies\nwith commonly used storage backends (Redis, Memcached & MongoDB).\n\nThe library provides identical APIs for use in sync and\n`async `_ codebases.\n\n\nSupported Strategies\n====================\n\nAll strategies support the follow methods:\n\n- `hit `_: consume a request.\n- `test `_: check if a request is allowed.\n- `get_window_stats `_: retrieve remaining quota and reset time.\n\nFixed Window\n------------\n`Fixed Window `_\n\nThis strategy is the most memory‑efficient because it uses a single counter per resource and\nrate limit. When the first request arrives, a window is started for a fixed duration\n(e.g., for a rate limit of 10 requests per minute the window expires in 60 seconds from the first request).\nAll requests in that window increment the counter and when the window expires, the counter resets.\n\nBurst traffic that bypasses the rate limit may occur at window boundaries.\n\nFor example, with a rate limit of 10 requests per minute:\n\n- At **00:00:45**, the first request arrives, starting a window from **00:00:45** to **00:01:45**.\n- All requests between **00:00:45** and **00:01:45** count toward the limit.\n- If 10 requests occur at any time in that window, any further request before **00:01:45** is rejected.\n- At **00:01:45**, the counter resets and a new window starts which would allow 10 requests\n until **00:02:45**.\n\nMoving Window\n-------------\n`Moving Window `_\n\nThis strategy adds each request’s timestamp to a log if the ``nth`` oldest entry (where ``n``\nis the limit) is either not present or is older than the duration of the window (for example with a rate limit of\n``10 requests per minute`` if there are either less than 10 entries or the 10th oldest entry is at least\n60 seconds old). Upon adding a new entry to the log \"expired\" entries are truncated.\n\nFor example, with a rate limit of 10 requests per minute:\n\n- At **00:00:10**, a client sends 1 requests which are allowed.\n- At **00:00:20**, a client sends 2 requests which are allowed.\n- At **00:00:30**, the client sends 4 requests which are allowed.\n- At **00:00:50**, the client sends 3 requests which are allowed (total = 10).\n- At **00:01:11**, the client sends 1 request. The strategy checks the timestamp of the\n 10th oldest entry (**00:00:10**) which is now 61 seconds old and thus expired. The request\n is allowed.\n- At **00:01:12**, the client sends 1 request. The 10th oldest entry's timestamp is **00:00:20**\n which is only 52 seconds old. The request is rejected.\n\nSliding Window Counter\n------------------------\n`Sliding Window Counter `_\n\nThis strategy approximates the moving window while using less memory by maintaining\ntwo counters:\n\n- **Current bucket:** counts requests in the ongoing period.\n- **Previous bucket:** counts requests in the immediately preceding period.\n\nWhen a request arrives, the effective request count is calculated as::\n\n weighted_count = current_count + floor(previous_count * weight)\n\nThe weight is based on how much time has elapsed in the current bucket::\n\n weight = (bucket_duration - elapsed_time) / bucket_duration\n\nIf ``weighted_count`` is below the limit, the request is allowed.\n\nFor example, with a rate limit of 10 requests per minute:\n\nAssume:\n\n- The current bucket (spanning **00:01:00** to **00:02:00**) has 8 hits.\n- The previous bucket (spanning **00:00:00** to **00:01:00**) has 4 hits.\n\nScenario 1:\n\n- A new request arrives at **00:01:30**, 30 seconds into the current bucket.\n- ``weight = (60 - 30) / 60 = 0.5``.\n- ``weighted_count = floor(8 + (4 * 0.5)) = floor(8 + 2) = 10``.\n- Since the weighted count equals the limit, the request is rejected.\n\nScenario 2:\n\n- A new request arrives at **00:01:40**, 40 seconds into the current bucket.\n- ``weight = (60 - 40) / 60 ≈ 0.33``.\n- ``weighted_count = floor(8 + (4 * 0.33)) = floor(8 + 1.32) = 9``.\n- Since the weighted count is below the limit, the request is allowed.\n\n\nStorage backends\n================\n\n- `Redis `_\n- `Memcached `_\n- `MongoDB `_\n- `In-Memory `_\n\nDive right in\n=============\n\nInitialize the storage backend\n\n.. code-block:: python\n\n from limits import storage\n backend = storage.MemoryStorage()\n # or memcached\n backend = storage.MemcachedStorage(\"memcached://localhost:11211\")\n # or redis\n backend = storage.RedisStorage(\"redis://localhost:6379\")\n # or mongodb\n backend = storage.MongoDbStorage(\"mongodb://localhost:27017\")\n # or use the factory\n storage_uri = \"memcached://localhost:11211\"\n backend = storage.storage_from_string(storage_uri)\n\nInitialize a rate limiter with a strategy\n\n.. code-block:: python\n\n from limits import strategies\n strategy = strategies.MovingWindowRateLimiter(backend)\n # or fixed window\n strategy = strategies.FixedWindowRateLimiter(backend)\n # or sliding window\n strategy = strategies.SlidingWindowCounterRateLimiter(backend)\n\n\nInitialize a rate limit\n\n.. code-block:: python\n\n from limits import parse\n one_per_minute = parse(\"1/minute\")\n\nInitialize a rate limit explicitly\n\n.. code-block:: python\n\n from limits import RateLimitItemPerSecond\n one_per_second = RateLimitItemPerSecond(1, 1)\n\nTest the limits\n\n.. code-block:: python\n\n import time\n assert True == strategy.hit(one_per_minute, \"test_namespace\", \"foo\")\n assert False == strategy.hit(one_per_minute, \"test_namespace\", \"foo\")\n assert True == strategy.hit(one_per_minute, \"test_namespace\", \"bar\")\n\n assert True == strategy.hit(one_per_second, \"test_namespace\", \"foo\")\n assert False == strategy.hit(one_per_second, \"test_namespace\", \"foo\")\n time.sleep(1)\n assert True == strategy.hit(one_per_second, \"test_namespace\", \"foo\")\n\nCheck specific limits without hitting them\n\n.. code-block:: python\n\n assert True == strategy.hit(one_per_second, \"test_namespace\", \"foo\")\n while not strategy.test(one_per_second, \"test_namespace\", \"foo\"):\n time.sleep(0.01)\n assert True == strategy.hit(one_per_second, \"test_namespace\", \"foo\")\n\nQuery available capacity and reset time for a limit\n\n.. code-block:: python\n\n assert True == strategy.hit(one_per_minute, \"test_namespace\", \"foo\")\n window = strategy.get_window_stats(one_per_minute, \"test_namespace\", \"foo\")\n assert window.remaining == 0\n assert False == strategy.hit(one_per_minute, \"test_namespace\", \"foo\")\n time.sleep(window.reset_time - time.time())\n assert True == strategy.hit(one_per_minute, \"test_namespace\", \"foo\")\n\n\nLinks\n=====\n\n* `Documentation `_\n* `Benchmarks `_\n* `Changelog `_\n\n","description_content_type":null,"docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":["Author","Author-Email","Classifier","Description","Home-Page","License","License-File","Project-Url","Provides-Extra","Requires-Dist","Requires-Python","Summary"],"home_page":"https://limits.readthedocs.org","keywords":null,"license":"MIT","license_expression":null,"license_files":["LICENSE.txt"],"maintainer":null,"maintainer_email":null,"name":"limits","package_url":"https://pypi.org/project/limits/","platform":null,"project_url":"https://pypi.org/project/limits/","project_urls":{"Homepage":"https://limits.readthedocs.org","Source":"https://github.com/alisaifee/limits"},"provides_extra":["redis","rediscluster","memcached","mongodb","valkey","async-redis","async-memcached","async-mongodb","async-valkey","all"],"release_url":"https://pypi.org/project/limits/5.2.0/","requires_dist":["deprecated>=1.2","packaging<26,>=21","typing_extensions","redis!=4.5.2,!=4.5.3,<6.0.0,>3; extra == \"redis\"","redis!=4.5.2,!=4.5.3,>=4.2.0; extra == \"rediscluster\"","pymemcache<5.0.0,>3; extra == \"memcached\"","pymongo<5,>4.1; extra == \"mongodb\"","valkey>=6; extra == \"valkey\"","coredis<5,>=3.4.0; extra == \"async-redis\"","memcachio>=0.3; extra == \"async-memcached\"","motor<4,>=3; extra == \"async-mongodb\"","valkey>=6; extra == \"async-valkey\"","redis!=4.5.2,!=4.5.3,<6.0.0,>3; extra == \"all\"","redis!=4.5.2,!=4.5.3,>=4.2.0; extra == \"all\"","pymemcache<5.0.0,>3; extra == \"all\"","pymongo<5,>4.1; extra == \"all\"","valkey>=6; extra == \"all\"","coredis<5,>=3.4.0; extra == \"all\"","memcachio>=0.3; extra == \"all\"","motor<4,>=3; extra == \"all\"","valkey>=6; extra == \"all\""],"requires_python":">=3.10","summary":"Rate limiting utilities","version":"5.2.0","yanked":false,"yanked_reason":null}

Dependency	Optional
deprecated	false
packaging	false
typing_extensions	false
coredis	true
memcachio	true
motor	true
pymemcache	true
pymongo	true
redis	true
valkey	true

Package search

limits

project_urls

Dependencies

All package metadata

Releases