# FastRateLimiter v1.1.0
`FastRateLimiter` is a high-performance and decorator-free rate limit class for Python. Features:
- You can use it in any web framework like FastAPI, Django, Flask, Tornado, Bottle, etc;
- The decision whether access can be granted or not is made in less than 0.00001 second and can handle over [50,000 calls per second](#speed-test);
- Accepts IPv4 and IPv6 simultaneously with the same response time;
- It works with a rate limit per second or in an advanced mode where you define the evaluation time and the blocking time, for example: 10 accesses in 5 seconds, receives a 5-second block;
- It has the NoLimitList, a list of IPs or network blocks (CIDR) where the listed IPs will not suffer limits. The average response time of this list is 0.000005 second regardless of the list size, and this list can be modified at runtime, allowing you to add or remove IPs or CIDRs without having to recreate the `FastRateLimiter` object;
- The NoLimitList (after version 1.1.0) can normalize invalid CIDRs, so you can add `10.10.10.10/8` and it will be converted to `10.0.0.0/8` automatically and will avoid CIDRs overlapping, if you add `10.0.0.0/8` and try to add `10.10.10.0/24`, it will be rejected.
- Can generate statistics on how many times a given IP has been blocked;
- You can evaluate the list of currently blocked IPs and the time at which each of the blocked IPs will be released;
- Precise `block_time` based on milliseconds. If the `block_time` is for 5 seconds and the REMOTE_HOST_IP reached the limit at second 12.123456, the release will only occur after second 17.123456 ([See below](#block-time-precision));
- Extremely easy to use:
```python
from fastratelimiter import FastRateLimiter
# PER SECOND MODE: More than 5 hits in a 1 second period receives a block until the end of the current second
rate_limiter = FastRateLimiter(rate_limit=5)
# ADVANCED MODE: More than 5 hits in a 5 second period receives a 2 second block
rate_limiter = FastRateLimiter(rate_limit=5,per=5,block_time=2)
if rate_limiter(remote_host_ip):
print(f">>> Rate limit exceeded for IP {remote_host_ip}")
# return your 429 Too Many Requests error
else:
print(f">>> Access granted to the IP {remote_host_ip}")
# continue with your API code
```
- A verbose mode for debugging problems. Just export the environment variable `export FASTRATELIMITER_DEBUG=1` or create the object with parameter `debug=True` for Windows aplications;
- Works on Linux, MacOS and Windows;
- No external dependencies, is Pure Python! you can just copy the `fastratelimiter.py` file to your project and use it without installing anything;
---
```
What's new in v1.1.0 - 11/July/2025
- The NoLimitList class was completely rewritten (based on UnlimitedIPList https://github.com/rabuchaim/UnlimitedIPList), now it is faster and more efficient, can normalize invalid CIDRs and avoid CIDRs overlapping.
What's new in v1.0.3 - 22/Jun/2025
- Only cosmetic changes, nothing that impacts functionality
- Fix in speed_test() function
- Improvements to the NoLimitList class
What's new in v1.0.2 - 22/May/2025
- Fix in @block_time.setter. Impacted those who tried to change the block_time at runtime.
- Fix in __int2ip functions, now all IPv6 returns the full expanded zero-padded form. Only impacted my unit test.
- I hid some internal lists of the NoLimitList list-type object.
```
---
## 🚀 Installation
```bash
pip install fastratelimiter
```
---
## 🔧 Requirements
- Python 3.10+ and nothing more!
---
## 🖉 `FastRateLimiter` Class Parameters
For most uses, you do not need to change any class parameters.
| Parameter | Type | Default Value | Description |
| ------------------------------------- | ------------- | --------------------------- | ---------------------------------------- |
| `rate_limit` | `int` | (required) | Maximum number of allowed requests per time window |
| `per` | `int` | `1` | Time window in seconds for applying the rate limit |
| `block_time` | `int` | `0` | Duration (in seconds) to block a client after exceeding the limit (0 = blocking until the end of the current second) |
| `no_limit_list` | `List[str]` | `[]` | List of IPs or Networks CIDR that are exempt from rate limiting |
| `with_stats` | `bool` | `False` | Enables usage statistics tracking |
| `cache_cleanup_interval` | `int` | `3` | Interval in seconds to automatically clean up stale cache entries |
| `lru_cache_maxsize` | `int` | `512` | Maximum size of the LRU cache used to store cache for some functions (IP access check is never cached) |
| `debug` | `bool` | `False` | Enable the debug messages. When enabled, this parameter overrides the checking of the FASTRATELIMITER_DEBUG environment variable. |
| `normalize_invalid_cidr` | `bool` | `False` | Enable the normalization of invalid CIDRs. When enabled, the library will attempt to fix any invalid CIDRs before using them. |
For debugging, you can also export the environment variable as shown below:
```bash
export FASTRATELIMITER_DEBUG=1
```
### Class Parameters Instructions
- `rate_limit`: Enter the maximum number of requests that will be allowed within the window defined in the `per` parameter. **You can change this value at any time without having to recreate the object.**
- `per`: Enter the time window where the `rate_limit` parameter will be evaluated. **You can change this value at any time without having to recreate the object.**
- `block_time`: Specify the blocking time if an IP reaches the number specified in the `rate_limit` parameter within the time window specified in the `per` parameter. If you specify 0, the IP will be released as soon as the current second changes. **You can change this value at any time without having to recreate the object.**
- `debug`: If you want to enable the debug mode, set this parameter to True or export the environment variable `FASTRATELIMITER_DEBUG=1`. **You can enable debugging using the environment variable any time without having to recreate the object.**
- The debug messages will be printed to the console and will include information about blocked IPs, access granted, and other relevant details.
- `normalize_invalid_cidr`: If you want to enable the normalization of invalid CIDRs of NoLimitList, set this parameter to True.
- `no_limit_list`: Here you can enter the IPs or network blocks (CIDR) that will be exempt from the rate limit check, that is, you can make as many calls as you want without being blocked and they will not be included in the statistics. **You can add or remove IPs from this list at runtime.** Ex: `['1.1.1.1','2.2.2.2/32','3.3.3.0/24','10.0.0.0/8']`.
>> Attention: `10.0.0.10/8` is AN INVALID CIDR - `10.0.0.0/8` is A VALID CIDR - `10.0.0.10/32` is A VALID CIDR.
>> From version 1.1.0, the NoLimitList can normalize invalid CIDRs, so you can add `10.10.10.10/24` and it will be converted to `10.10.10.0/24`. And automatically will avoid CIDRs overlapping, if you add `10.10.10.0/24` and try to add `10.10.10.10/32`, it will be rejected.
- **NoLimitList Management**: The `FastRateLimiter.no_limit_list` is a list-type object to manage the list of allowed networks and perform quick searches. **You can add or remove IPs from this list at runtime.**
- `last_discarted_ips`: It is a property that is fed whenever an invalid IP or CIDR is found, either by the `set_list` or `add_ip` or `add_ips` methods.
- `def set_list(self,items:List[str])`: Set a new list
- `def get_list(self)->List[str]`: Get the current no limit list
- `def add_ip(self,ipaddr:str)`: Add an ip address or CIDR to no limit list
- `def add_ips(self,ipaddr_list:List[str])`: Add a list of ip addressess or CIDRs to no limit list
- `def remove_ip(self,ipaddr:str)`: Remove an ip address or a CIDR from no limit list
- `def remove_ips(self,ipaddr_list:List[str])`: Remove a list of ip addressess or a CIDRs from no limit list
- `def check_ipaddr(self,ipaddr:str)->bool`: Check if an IP address is in the no limit list. Returns a tuple with the search response (True or False) and if True, it also returns the network that the IP fits into, otherwise it returns None. (Elapsed average time: 0.000006).
- `def check_iplong(self,iplong:int)->tuple`: Check if an "IP address as integer (iplong)" is in the no limit list. Returns a tuple with the search response (True or False) and if True, it also returns the network that the IP fits into, otherwise it returns None. (Elapsed average time: 0.000002)
```python
# This is the code for the __call__ function of FastRateLimiter, you don't need to worry about checking the NoLimitList
rate_limiter = FastRateLimiter(no_limit_list=['1.1.1.1','2.2.2.2/32','3.3.3.0/24','10.0.0.0/8','10.10.10.10/8','a.b.c.d','9.9.9.9/XX'])
print(f"Invalid IPs/CIDR found in no_limit_list: {rate_limiter.no_limit_list.last_discarted_ips}")
print(f"Current no_limit_list: {rate_limiter.no_limit_list}")
start_time = time.monotonic()
no_limit_result, no_limit_network = rate_limiter.no_limit_list.check_ipaddr(ipaddr)
# no_limit_result, no_limit_network = rate_limiter.no_limit_list.check_iplong(iplong)
if no_limit_result:
rate_limiter.__debug(f"IP address {ipaddr} is in the no limit list - network {no_limit_network} [{'%.9f'%(time.monotonic()-start_time)}]")
return False
else:
return rate_limiter.__call_rate_limit(iplong,ipaddr)
```
`no_limit_result` can be True or False and `no_limit_network` can be a network CIDR or None.
- `with_stats`: Enables access statistics, where it is recorded how many times a given IP is blocked. It is not the number of times that access is denied, a single occurrence is recorded per IP, per block and per period. **If statistics are enabled and the rate limiting feature is used heavily, it is a good idea to clear the statistics from time to time. You can use the `get_stats(reset_stats=True)` function to reset the statistics after collecting them.**
- `FastRateLimiter.get_stats(top_items:int=10,reset_stats:bool=False)`: Returns a dictionary with the IP and the number of times blocked.
```{'10.0.0.10': 6, 'bf06:d2b3:c8e:fc7d:3839:9130:8c89:738e': 5}```
- `FastRateLimiter.reset_stats()`: Clear all statistics data.
- `cache_cleanup_interval`: When an IP is checked and does not reach the limit within the established period, if it no longer passes through the application, the data remains in memory, and it is necessary to clean it so that it does not grow indefinitely. This value is used for automatic cache cleaning for PER SECOND mode. For ADVANCED mode, the recurrence is automatic and occurs every 0.1 second with no possibility of change.
- `FastRateLimiter.cache_info()`: Returns a named tuple with the number of items and the size in kbytes of the __rate_limit_cache variable and also the memory consumption (Rss).
```CacheInfo(items=2, size_in_kb=0.21, memory_in_mb=12.93)```
- `FastRateLimiter.cache_clear()`: Clear all rate limit cache.
- `lru_cache_maxsize`: Some functions are repetitive and are subject to caching to improve application performance. The `lru_cache_maxsize` parameter controls the amount of memory used to maintain this cache. Only functions that handle IP to integer conversion are cached.
## Example using Tornado:
```python
from fastratelimiter import FastRateLimiter
import asyncio, tornado
class MainHandler(tornado.web.RequestHandler):
def get(self):
if rate_limiter(self.request.remote_ip):
print(f">>> Rate limit exceeded for IP {self.request.remote_ip}")
self.send_error(429,reason=f"Calm down boy! Too many requests from IP {self.request.remote_ip}")
else:
print(f">>> Access granted to the IP {self.request.remote_ip}")
# continue with your API code
self.write("Hello, world")
def make_app():
return tornado.web.Application([(r"/", MainHandler),])
async def main():
app = make_app()
app.listen(8888)
await asyncio.Event().wait()
if __name__ == "__main__":
rate_limiter = FastRateLimiter(rate_limit=5, per=2, block_time=5, with_stats=True, no_limit_list=['10.0.0.0/8'], debug=True)
asyncio.run(main())
```
```bash
$ ./tornado_example.py
>>> Access granted to the IP 127.0.0.1
>>> Access granted to the IP 127.0.0.1
>>> Access granted to the IP 127.0.0.1
>>> Access granted to the IP 127.0.0.1
>>> Access granted to the IP 127.0.0.1
>>> Rate limit exceeded for IP 127.0.0.1
429 GET / (127.0.0.1) 0.35ms
25/05/20 08:18:30.298263 [FASTRATELIMITER_DEBUG] IP 127.0.0.1 blocked until 2025-05-20 08:18:35.293630 [0.000040126]
>>> Rate limit exceeded for IP 127.0.0.1
429 GET / (127.0.0.1) 0.76ms
25/05/20 08:18:30.303110 [FASTRATELIMITER_DEBUG] IP 127.0.0.1 blocked until 2025-05-20 08:18:35.293630 [0.000012463]
>>> Rate limit exceeded for IP 127.0.0.1
429 GET / (127.0.0.1) 0.44ms
25/05/20 08:18:30.307074 [FASTRATELIMITER_DEBUG] IP 127.0.0.1 blocked until 2025-05-20 08:18:35.293630 [0.000006696]
>>> Rate limit exceeded for IP 127.0.0.1
429 GET / (127.0.0.1) 0.29ms
```
```bash
$ while true; do curl -v http://127.0.0.1:8888/; sleep 0.1; done
* Trying 127.0.0.1:8888...
* Connected to 127.0.0.1 (127.0.0.1) port 8888
> GET / HTTP/1.1
> Host: 127.0.0.1:8888
> User-Agent: curl/8.6.0
> Accept: */*
>
< HTTP/1.1 429 Calm down boy! Too many requests from IP 127.0.0.1
< Server: TornadoServer/6.4.1
< Content-Type: text/html; charset=UTF-8
< Date: Tue, 20 May 2025 11:19:47 GMT
< Content-Length: 151
```
## Example using FastAPI:
```python
from fastratelimiter import FastRateLimiter
from fastapi import FastAPI, Request, HTTPException, status
app = FastAPI()
rate_limiter = FastRateLimiter(rate_limit=5, per=2, block_time=5, with_stats=True, no_limit_list=['10.0.0.0/8'])
@app.get("/")
async def root(request: Request):
if rate_limiter(request.client.host):
print(f">>> Rate limit exceeded for IP {request.client.host}")
raise HTTPException(status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail=f"Calm down boy! Too many requests from IP {request.client.host}")
else:
print(f">>> Access granted to the IP {request.client.host}")
# continue with your API code
return {"Hello": "World"}
```
```bash
# uvicorn test_fastapi:app
INFO: Started server process [29573]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
## More examples
| A PER SECOND example | An ADVANCED MODE example |
| ------------------------------------- | ------------- |
|<img src="https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_04.png" width="600" />|<img src="https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_05.png" width="600" />|
| FastRateLimiter Blocked IPs and Stats | FastRateLimiter Cache Info |
| ------------------------------------- | ------------- |
|<img src="https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_06.png" width="600" />|<img src="https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_07.png" width="600" />|
## Block Time Precision
As we can see in the first screenshot below, 1 IPv4 and 1 IPv6 with a FastRateLimiter object created with the parameters `rate_limit=5,per=5,block_time=2,with_stats=True`, were blocked at `06:32:07.793020 (ipv4)` and `06:32:07.7930047 (ipv6)`.
<img src="https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_02.png" width="800" />
In the second screenshot we see that they were released 2 seconds later and only had access after `06:32:09.793058 (ipv4)` and `06:32:09.793137 (ipv6)`.
>>*Note that in these 2 seconds more than 226,770 requests were denied*
<img src="https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_03.png" width="800" />
>> **There may be a difference of up to 0.1 seconds due to the cache_cleanup_interval of Advanced mode being 0.1 second.**
## Speed Test
Create the FastRateLimiter object and call the function below:
```python
>>> from fastratelimiter import FastRateLimiter
>>> rate_limiter = FastRateLimiter(rate_limit=5,per=5,block_time=2,with_stats=False)
>>> rate_limiter.speed_test(max_ips=500000)
```
<img src="https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_01.png" width="800" />
---
## 🌐 Links
- **GitHub**: [github.com/rabuchaim/fastratelimiter](https://github.com/rabuchaim/fastratelimiter)
- **PyPI**: [pypi.org/project/fastratelimiter](https://pypi.org/project/fastratelimiter)
- **Bugs / Issues**: [issues page](https://github.com/rabuchaim/fastratelimiter/issues)
---
## ⚖️ License
MIT License
---
## 🙌 Author
Ricardo Abuchaim ([ricardoabuchaim@gmail.com](mailto\:ricardoabuchaim@gmail.com)) - [github.com/rabuchaim](https://github.com/rabuchaim)
---
Contributions, testing, ideas, or feedback are very welcome! 🌟
Raw data
{
"_id": null,
"home_page": "https://github.com/rabuchaim/fastratelimiter",
"name": "fastratelimiter",
"maintainer": "Ricardo Abuchaim",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "ricardoabuchaim@gmail.com",
"keywords": "ratelimit, ratelimiter, fastratelimiter, api, rate limit, firewall, blocking, flask, tornado, fastapi, bottle, purepython, pure, rules, tools",
"author": "Ricardo Abuchaim",
"author_email": "ricardoabuchaim@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6c/3d/7ad47ea92c9f6da90b179554a6b721b81b2d8e463f8d0e1e025000304413/fastratelimiter-1.1.0.tar.gz",
"platform": null,
"description": "# FastRateLimiter v1.1.0\n\n`FastRateLimiter` is a high-performance and decorator-free rate limit class for Python. Features:\n\n- You can use it in any web framework like FastAPI, Django, Flask, Tornado, Bottle, etc;\n\n- The decision whether access can be granted or not is made in less than 0.00001 second and can handle over [50,000 calls per second](#speed-test);\n\n- Accepts IPv4 and IPv6 simultaneously with the same response time;\n\n- It works with a rate limit per second or in an advanced mode where you define the evaluation time and the blocking time, for example: 10 accesses in 5 seconds, receives a 5-second block;\n\n- It has the NoLimitList, a list of IPs or network blocks (CIDR) where the listed IPs will not suffer limits. The average response time of this list is 0.000005 second regardless of the list size, and this list can be modified at runtime, allowing you to add or remove IPs or CIDRs without having to recreate the `FastRateLimiter` object;\n\n- The NoLimitList (after version 1.1.0) can normalize invalid CIDRs, so you can add `10.10.10.10/8` and it will be converted to `10.0.0.0/8` automatically and will avoid CIDRs overlapping, if you add `10.0.0.0/8` and try to add `10.10.10.0/24`, it will be rejected.\n\n- Can generate statistics on how many times a given IP has been blocked;\n\n- You can evaluate the list of currently blocked IPs and the time at which each of the blocked IPs will be released;\n\n- Precise `block_time` based on milliseconds. If the `block_time` is for 5 seconds and the REMOTE_HOST_IP reached the limit at second 12.123456, the release will only occur after second 17.123456 ([See below](#block-time-precision));\n\n- Extremely easy to use:\n\n```python\nfrom fastratelimiter import FastRateLimiter\n# PER SECOND MODE: More than 5 hits in a 1 second period receives a block until the end of the current second\nrate_limiter = FastRateLimiter(rate_limit=5) \n# ADVANCED MODE: More than 5 hits in a 5 second period receives a 2 second block\nrate_limiter = FastRateLimiter(rate_limit=5,per=5,block_time=2) \nif rate_limiter(remote_host_ip):\n print(f\">>> Rate limit exceeded for IP {remote_host_ip}\")\n # return your 429 Too Many Requests error\nelse:\n print(f\">>> Access granted to the IP {remote_host_ip}\")\n # continue with your API code\n```\n\n- A verbose mode for debugging problems. Just export the environment variable `export FASTRATELIMITER_DEBUG=1` or create the object with parameter `debug=True` for Windows aplications;\n\n- Works on Linux, MacOS and Windows;\n\n- No external dependencies, is Pure Python! you can just copy the `fastratelimiter.py` file to your project and use it without installing anything;\n\n---\n\n```\nWhat's new in v1.1.0 - 11/July/2025\n- The NoLimitList class was completely rewritten (based on UnlimitedIPList https://github.com/rabuchaim/UnlimitedIPList), now it is faster and more efficient, can normalize invalid CIDRs and avoid CIDRs overlapping.\n\nWhat's new in v1.0.3 - 22/Jun/2025\n- Only cosmetic changes, nothing that impacts functionality\n- Fix in speed_test() function\n- Improvements to the NoLimitList class\n\nWhat's new in v1.0.2 - 22/May/2025\n- Fix in @block_time.setter. Impacted those who tried to change the block_time at runtime. \n- Fix in __int2ip functions, now all IPv6 returns the full expanded zero-padded form. Only impacted my unit test.\n- I hid some internal lists of the NoLimitList list-type object.\n```\n\n---\n\n## \ud83d\ude80 Installation\n\n```bash\npip install fastratelimiter\n```\n\n---\n\n## \ud83d\udd27 Requirements\n\n- Python 3.10+ and nothing more!\n\n---\n\n## \ud83d\udd89 `FastRateLimiter` Class Parameters\n\nFor most uses, you do not need to change any class parameters.\n\n| Parameter | Type | Default Value | Description |\n| ------------------------------------- | ------------- | --------------------------- | ---------------------------------------- |\n| `rate_limit` | `int` | (required) | Maximum number of allowed requests per time window |\n| `per` | `int` | `1` | Time window in seconds for applying the rate limit |\n| `block_time` | `int` | `0` | Duration (in seconds) to block a client after exceeding the limit (0 = blocking until the end of the current second) |\n| `no_limit_list` | `List[str]` | `[]` | List of IPs or Networks CIDR that are exempt from rate limiting |\n| `with_stats` | `bool` | `False` | Enables usage statistics tracking |\n| `cache_cleanup_interval` | `int` | `3` | Interval in seconds to automatically clean up stale cache entries |\n| `lru_cache_maxsize` | `int` | `512` | Maximum size of the LRU cache used to store cache for some functions (IP access check is never cached) |\n| `debug` | `bool` | `False` | Enable the debug messages. When enabled, this parameter overrides the checking of the FASTRATELIMITER_DEBUG environment variable. |\n| `normalize_invalid_cidr` | `bool` | `False` | Enable the normalization of invalid CIDRs. When enabled, the library will attempt to fix any invalid CIDRs before using them. |\n\nFor debugging, you can also export the environment variable as shown below:\n\n```bash\nexport FASTRATELIMITER_DEBUG=1\n```\n\n### Class Parameters Instructions\n\n- `rate_limit`: Enter the maximum number of requests that will be allowed within the window defined in the `per` parameter. **You can change this value at any time without having to recreate the object.**\n\n- `per`: Enter the time window where the `rate_limit` parameter will be evaluated. **You can change this value at any time without having to recreate the object.**\n\n- `block_time`: Specify the blocking time if an IP reaches the number specified in the `rate_limit` parameter within the time window specified in the `per` parameter. If you specify 0, the IP will be released as soon as the current second changes. **You can change this value at any time without having to recreate the object.**\n\n- `debug`: If you want to enable the debug mode, set this parameter to True or export the environment variable `FASTRATELIMITER_DEBUG=1`. **You can enable debugging using the environment variable any time without having to recreate the object.** \n\n - The debug messages will be printed to the console and will include information about blocked IPs, access granted, and other relevant details.\n\n- `normalize_invalid_cidr`: If you want to enable the normalization of invalid CIDRs of NoLimitList, set this parameter to True.\n\n- `no_limit_list`: Here you can enter the IPs or network blocks (CIDR) that will be exempt from the rate limit check, that is, you can make as many calls as you want without being blocked and they will not be included in the statistics. **You can add or remove IPs from this list at runtime.** Ex: `['1.1.1.1','2.2.2.2/32','3.3.3.0/24','10.0.0.0/8']`. \n\n >> Attention: `10.0.0.10/8` is AN INVALID CIDR - `10.0.0.0/8` is A VALID CIDR - `10.0.0.10/32` is A VALID CIDR.\n\n >> From version 1.1.0, the NoLimitList can normalize invalid CIDRs, so you can add `10.10.10.10/24` and it will be converted to `10.10.10.0/24`. And automatically will avoid CIDRs overlapping, if you add `10.10.10.0/24` and try to add `10.10.10.10/32`, it will be rejected.\n\n - **NoLimitList Management**: The `FastRateLimiter.no_limit_list` is a list-type object to manage the list of allowed networks and perform quick searches. **You can add or remove IPs from this list at runtime.**\n\n - `last_discarted_ips`: It is a property that is fed whenever an invalid IP or CIDR is found, either by the `set_list` or `add_ip` or `add_ips` methods.\n \n - `def set_list(self,items:List[str])`: Set a new list\n \n - `def get_list(self)->List[str]`: Get the current no limit list\n \n - `def add_ip(self,ipaddr:str)`: Add an ip address or CIDR to no limit list\n \n - `def add_ips(self,ipaddr_list:List[str])`: Add a list of ip addressess or CIDRs to no limit list\n \n - `def remove_ip(self,ipaddr:str)`: Remove an ip address or a CIDR from no limit list\n \n - `def remove_ips(self,ipaddr_list:List[str])`: Remove a list of ip addressess or a CIDRs from no limit list\n \n - `def check_ipaddr(self,ipaddr:str)->bool`: Check if an IP address is in the no limit list. Returns a tuple with the search response (True or False) and if True, it also returns the network that the IP fits into, otherwise it returns None. (Elapsed average time: 0.000006).\n \n - `def check_iplong(self,iplong:int)->tuple`: Check if an \"IP address as integer (iplong)\" is in the no limit list. Returns a tuple with the search response (True or False) and if True, it also returns the network that the IP fits into, otherwise it returns None. (Elapsed average time: 0.000002)\n \n ```python\n # This is the code for the __call__ function of FastRateLimiter, you don't need to worry about checking the NoLimitList\n rate_limiter = FastRateLimiter(no_limit_list=['1.1.1.1','2.2.2.2/32','3.3.3.0/24','10.0.0.0/8','10.10.10.10/8','a.b.c.d','9.9.9.9/XX'])\n print(f\"Invalid IPs/CIDR found in no_limit_list: {rate_limiter.no_limit_list.last_discarted_ips}\")\n print(f\"Current no_limit_list: {rate_limiter.no_limit_list}\")\n start_time = time.monotonic()\n no_limit_result, no_limit_network = rate_limiter.no_limit_list.check_ipaddr(ipaddr)\n # no_limit_result, no_limit_network = rate_limiter.no_limit_list.check_iplong(iplong)\n if no_limit_result:\n rate_limiter.__debug(f\"IP address {ipaddr} is in the no limit list - network {no_limit_network} [{'%.9f'%(time.monotonic()-start_time)}]\")\n return False\n else:\n return rate_limiter.__call_rate_limit(iplong,ipaddr)\n ```\n `no_limit_result` can be True or False and `no_limit_network` can be a network CIDR or None.\n\n- `with_stats`: Enables access statistics, where it is recorded how many times a given IP is blocked. It is not the number of times that access is denied, a single occurrence is recorded per IP, per block and per period. **If statistics are enabled and the rate limiting feature is used heavily, it is a good idea to clear the statistics from time to time. You can use the `get_stats(reset_stats=True)` function to reset the statistics after collecting them.**\n\n - `FastRateLimiter.get_stats(top_items:int=10,reset_stats:bool=False)`: Returns a dictionary with the IP and the number of times blocked.\n\n ```{'10.0.0.10': 6, 'bf06:d2b3:c8e:fc7d:3839:9130:8c89:738e': 5}```\n\n - `FastRateLimiter.reset_stats()`: Clear all statistics data.\n\n- `cache_cleanup_interval`: When an IP is checked and does not reach the limit within the established period, if it no longer passes through the application, the data remains in memory, and it is necessary to clean it so that it does not grow indefinitely. This value is used for automatic cache cleaning for PER SECOND mode. For ADVANCED mode, the recurrence is automatic and occurs every 0.1 second with no possibility of change.\n\n - `FastRateLimiter.cache_info()`: Returns a named tuple with the number of items and the size in kbytes of the __rate_limit_cache variable and also the memory consumption (Rss).\n\n ```CacheInfo(items=2, size_in_kb=0.21, memory_in_mb=12.93)```\n\n - `FastRateLimiter.cache_clear()`: Clear all rate limit cache.\n\n- `lru_cache_maxsize`: Some functions are repetitive and are subject to caching to improve application performance. The `lru_cache_maxsize` parameter controls the amount of memory used to maintain this cache. Only functions that handle IP to integer conversion are cached.\n\n## Example using Tornado:\n\n```python\nfrom fastratelimiter import FastRateLimiter\nimport asyncio, tornado\n\nclass MainHandler(tornado.web.RequestHandler):\n def get(self):\n if rate_limiter(self.request.remote_ip):\n print(f\">>> Rate limit exceeded for IP {self.request.remote_ip}\")\n self.send_error(429,reason=f\"Calm down boy! Too many requests from IP {self.request.remote_ip}\")\n else:\n print(f\">>> Access granted to the IP {self.request.remote_ip}\")\n # continue with your API code\n self.write(\"Hello, world\")\n \ndef make_app():\n return tornado.web.Application([(r\"/\", MainHandler),])\n\nasync def main():\n app = make_app()\n app.listen(8888)\n await asyncio.Event().wait()\n\nif __name__ == \"__main__\":\n rate_limiter = FastRateLimiter(rate_limit=5, per=2, block_time=5, with_stats=True, no_limit_list=['10.0.0.0/8'], debug=True)\n asyncio.run(main())\n```\n```bash\n$ ./tornado_example.py\n>>> Access granted to the IP 127.0.0.1\n>>> Access granted to the IP 127.0.0.1\n>>> Access granted to the IP 127.0.0.1\n>>> Access granted to the IP 127.0.0.1\n>>> Access granted to the IP 127.0.0.1\n>>> Rate limit exceeded for IP 127.0.0.1\n429 GET / (127.0.0.1) 0.35ms\n25/05/20 08:18:30.298263 [FASTRATELIMITER_DEBUG] IP 127.0.0.1 blocked until 2025-05-20 08:18:35.293630 [0.000040126]\n>>> Rate limit exceeded for IP 127.0.0.1\n429 GET / (127.0.0.1) 0.76ms\n25/05/20 08:18:30.303110 [FASTRATELIMITER_DEBUG] IP 127.0.0.1 blocked until 2025-05-20 08:18:35.293630 [0.000012463]\n>>> Rate limit exceeded for IP 127.0.0.1\n429 GET / (127.0.0.1) 0.44ms\n25/05/20 08:18:30.307074 [FASTRATELIMITER_DEBUG] IP 127.0.0.1 blocked until 2025-05-20 08:18:35.293630 [0.000006696]\n>>> Rate limit exceeded for IP 127.0.0.1\n429 GET / (127.0.0.1) 0.29ms\n```\n\n```bash\n$ while true; do curl -v http://127.0.0.1:8888/; sleep 0.1; done\n* Trying 127.0.0.1:8888...\n* Connected to 127.0.0.1 (127.0.0.1) port 8888\n> GET / HTTP/1.1\n> Host: 127.0.0.1:8888\n> User-Agent: curl/8.6.0\n> Accept: */*\n>\n< HTTP/1.1 429 Calm down boy! Too many requests from IP 127.0.0.1\n< Server: TornadoServer/6.4.1\n< Content-Type: text/html; charset=UTF-8\n< Date: Tue, 20 May 2025 11:19:47 GMT\n< Content-Length: 151\n```\n\n## Example using FastAPI:\n\n```python \nfrom fastratelimiter import FastRateLimiter\nfrom fastapi import FastAPI, Request, HTTPException, status\n\napp = FastAPI()\n\nrate_limiter = FastRateLimiter(rate_limit=5, per=2, block_time=5, with_stats=True, no_limit_list=['10.0.0.0/8'])\n\n@app.get(\"/\")\nasync def root(request: Request):\n \n if rate_limiter(request.client.host):\n print(f\">>> Rate limit exceeded for IP {request.client.host}\")\n raise HTTPException(status_code=status.HTTP_429_TOO_MANY_REQUESTS,\n detail=f\"Calm down boy! Too many requests from IP {request.client.host}\")\n else:\n print(f\">>> Access granted to the IP {request.client.host}\")\n # continue with your API code\n return {\"Hello\": \"World\"}\n```\n```bash\n# uvicorn test_fastapi:app\nINFO: Started server process [29573]\nINFO: Waiting for application startup.\nINFO: Application startup complete.\nINFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)\n```\n\n## More examples\n\n| A PER SECOND example | An ADVANCED MODE example | \n| ------------------------------------- | ------------- | \n|<img src=\"https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_04.png\" width=\"600\" />|<img src=\"https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_05.png\" width=\"600\" />| \n\n| FastRateLimiter Blocked IPs and Stats | FastRateLimiter Cache Info | \n| ------------------------------------- | ------------- | \n|<img src=\"https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_06.png\" width=\"600\" />|<img src=\"https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_07.png\" width=\"600\" />| \n\n\n## Block Time Precision\n\nAs we can see in the first screenshot below, 1 IPv4 and 1 IPv6 with a FastRateLimiter object created with the parameters `rate_limit=5,per=5,block_time=2,with_stats=True`, were blocked at `06:32:07.793020 (ipv4)` and `06:32:07.7930047 (ipv6)`. \n\n<img src=\"https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_02.png\" width=\"800\" />\n\nIn the second screenshot we see that they were released 2 seconds later and only had access after `06:32:09.793058 (ipv4)` and `06:32:09.793137 (ipv6)`. \n\n>>*Note that in these 2 seconds more than 226,770 requests were denied*\n\n<img src=\"https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_03.png\" width=\"800\" />\n\n>> **There may be a difference of up to 0.1 seconds due to the cache_cleanup_interval of Advanced mode being 0.1 second.**\n\n## Speed Test\n\nCreate the FastRateLimiter object and call the function below:\n\n```python\n>>> from fastratelimiter import FastRateLimiter\n>>> rate_limiter = FastRateLimiter(rate_limit=5,per=5,block_time=2,with_stats=False)\n>>> rate_limiter.speed_test(max_ips=500000)\n```\n\n<img src=\"https://raw.githubusercontent.com/rabuchaim/fastratelimiter/refs/heads/main/fastratelimiter_01.png\" width=\"800\" />\n\n---\n\n## \ud83c\udf10 Links\n\n- **GitHub**: [github.com/rabuchaim/fastratelimiter](https://github.com/rabuchaim/fastratelimiter)\n- **PyPI**: [pypi.org/project/fastratelimiter](https://pypi.org/project/fastratelimiter)\n- **Bugs / Issues**: [issues page](https://github.com/rabuchaim/fastratelimiter/issues)\n\n---\n\n## \u2696\ufe0f License\n\nMIT License\n\n---\n\n## \ud83d\ude4c Author\n\nRicardo Abuchaim ([ricardoabuchaim@gmail.com](mailto\\:ricardoabuchaim@gmail.com)) - [github.com/rabuchaim](https://github.com/rabuchaim)\n\n---\n\nContributions, testing, ideas, or feedback are very welcome! \ud83c\udf1f\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "FastRateLimiter is a high-performance, decorator-free rate limiter for Python. Compatible with any web framework, ultra-fast (<0.00001s), supports IPv4/IPv6 simultaneously, has per-second and advanced limits, whitelisting capabilities, precise block/release timing (in milliseconds), and full customization \u2014 all in pure Python.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/rabuchaim/fastratelimiter",
"Issue Tracker": "https://github.com/rabuchaim/fastratelimiter/issues",
"Source code": "https://github.com/rabuchaim/fastratelimiter"
},
"split_keywords": [
"ratelimit",
" ratelimiter",
" fastratelimiter",
" api",
" rate limit",
" firewall",
" blocking",
" flask",
" tornado",
" fastapi",
" bottle",
" purepython",
" pure",
" rules",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6c3d7ad47ea92c9f6da90b179554a6b721b81b2d8e463f8d0e1e025000304413",
"md5": "c0fb7f4f6b9071b32fb0c6e104fa7eb5",
"sha256": "bd4719cde47e2b056777ae797c87232e3986e78bc5b67f7cf332b3dd10185a7f"
},
"downloads": -1,
"filename": "fastratelimiter-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c0fb7f4f6b9071b32fb0c6e104fa7eb5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 26795,
"upload_time": "2025-07-11T05:42:38",
"upload_time_iso_8601": "2025-07-11T05:42:38.863911Z",
"url": "https://files.pythonhosted.org/packages/6c/3d/7ad47ea92c9f6da90b179554a6b721b81b2d8e463f8d0e1e025000304413/fastratelimiter-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 05:42:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rabuchaim",
"github_project": "fastratelimiter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fastratelimiter"
}
JSON
