slideguard 0.1.0__tar.gz

slideguard-0.1.0/PKG-INFO

@@ -0,0 +1,4 @@
+Metadata-Version: 2.4
+Name: slideguard
+Version: 0.1.0
+Requires-Python: >=3.9

slideguard-0.1.0/README.md

@@ -0,0 +1,80 @@
+# slideguard
+
+A lightweight, open-source Python rate limiter.
+
+- PyPI package name: `slideguard`
+- Import path: `ratelimiter`
+
+## Features
+
+- Timestamp-window based rate limiting
+- Simple `@rate_limit(calls=N, per=seconds)` decorator
+- Custom `RateLimitExceeded` exception
+- Thread-safe decorator implementation
+
+## Installation
+
+From PyPI (after publishing):
+
+```bash
+pip install slideguard
+```
+
+From source:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+### 1) Use `is_allowed` directly
+
+```python
+import time
+from ratelimiter import is_allowed
+
+calls = []
+
+allowed, calls = is_allowed(calls, max_calls=5, window=60)
+if allowed:
+    calls.append(time.time())
+    print("Call accepted")
+else:
+    print("Call blocked")
+```
+
+### 2) Use the `@rate_limit` decorator
+
+```python
+from ratelimiter import RateLimitExceeded, rate_limit
+
+
+@rate_limit(calls=5, per=60)
+def send_event(payload: dict) -> str:
+    return f"sent: {payload['id']}"
+
+
+try:
+    result = send_event({"id": "evt-1"})
+    print(result)
+except RateLimitExceeded as exc:
+    print(f"Blocked by rate limiter: {exc}")
+```
+
+## Running tests
+
+```bash
+python -m pytest -q
+```
+
+## Open source
+
+This project is open source and contributions are welcome.
+
+Suggested contribution flow:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add or update tests
+4. Open a pull request

slideguard-0.1.0/pyproject.toml

@@ -0,0 +1,11 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "slideguard"
+version = "0.1.0"
+requires-python = ">=3.9"
+
+[tool.setuptools.packages.find]
+include = ["ratelimiter*"]

slideguard-0.1.0/ratelimiter/__init__.py

@@ -0,0 +1,5 @@
+from .core import is_allowed
+from .decorator import rate_limit
+from .exceptions import RateLimitExceeded
+
+__all__ = ["is_allowed", "rate_limit", "RateLimitExceeded"]

slideguard-0.1.0/ratelimiter/core.py

@@ -0,0 +1,12 @@
+from time import time
+
+
+def is_allowed(calls: list[float], max_calls: int, window: float) -> tuple[bool, list[float]]:
+	"""Return whether a new call is allowed and the cleaned list of calls.
+
+	Expired timestamps are those older than `window` seconds from now.
+	"""
+	now = time()
+	calls[:] = [timestamp for timestamp in calls if now - timestamp <= window]
+	allowed = len(calls) < max_calls
+	return allowed, calls

slideguard-0.1.0/ratelimiter/decorator.py

@@ -0,0 +1,35 @@
+from functools import wraps
+from threading import Lock
+from time import time
+from typing import Callable, ParamSpec, TypeVar
+
+from .core import is_allowed
+from .exceptions import RateLimitExceeded
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def rate_limit(calls: int, per: float) -> Callable[[Callable[P, R]], Callable[P, R]]:
+	"""Limit function execution to `calls` within `per` seconds."""
+
+	def decorator(func: Callable[P, R]) -> Callable[P, R]:
+		timestamps: list[float] = []
+		lock = Lock()
+
+		@wraps(func)
+		def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+			with lock:
+				allowed, _ = is_allowed(timestamps, calls, per)
+				if not allowed:
+					raise RateLimitExceeded(
+						f"Rate limit exceeded: max {calls} calls per {per} seconds"
+					)
+
+				timestamps.append(time())
+			return func(*args, **kwargs)
+
+		return wrapper
+
+	return decorator
+

slideguard-0.1.0/ratelimiter/exceptions.py

@@ -0,0 +1,3 @@
+class RateLimitExceeded(Exception):
+	"""Raised when a call is blocked by the rate limiter."""
+

slideguard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

slideguard-0.1.0/slideguard.egg-info/PKG-INFO

@@ -0,0 +1,4 @@
+Metadata-Version: 2.4
+Name: slideguard
+Version: 0.1.0
+Requires-Python: >=3.9

slideguard-0.1.0/slideguard.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+ratelimiter/__init__.py
+ratelimiter/core.py
+ratelimiter/decorator.py
+ratelimiter/exceptions.py
+slideguard.egg-info/PKG-INFO
+slideguard.egg-info/SOURCES.txt
+slideguard.egg-info/dependency_links.txt
+slideguard.egg-info/top_level.txt
+tests/test_ratelimiter.py

slideguard-0.1.0/slideguard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

slideguard-0.1.0/slideguard.egg-info/top_level.txt

@@ -0,0 +1 @@
+ratelimiter

slideguard-0.1.0/tests/test_ratelimiter.py

@@ -0,0 +1,85 @@
+import threading
+from unittest.mock import patch
+
+import pytest
+
+from ratelimiter import RateLimitExceeded, rate_limit
+
+
+def test_calls_within_limit_pass() -> None:
+    @rate_limit(calls=3, per=60)
+    def multiply_by_two(value: int) -> int:
+        return value * 2
+
+    with patch("ratelimiter.core.time", return_value=1000.0), patch(
+        "ratelimiter.decorator.time", return_value=1000.0
+    ):
+        assert multiply_by_two(1) == 2
+        assert multiply_by_two(2) == 4
+        assert multiply_by_two(3) == 6
+
+
+def test_call_exceeding_limit_raises() -> None:
+    @rate_limit(calls=2, per=60)
+    def ping() -> str:
+        return "pong"
+
+    with patch("ratelimiter.core.time", return_value=1000.0), patch(
+        "ratelimiter.decorator.time", return_value=1000.0
+    ):
+        assert ping() == "pong"
+        assert ping() == "pong"
+        with pytest.raises(RateLimitExceeded):
+            ping()
+
+
+def test_calls_allowed_again_after_window_expires() -> None:
+    @rate_limit(calls=2, per=10)
+    def ping() -> str:
+        return "pong"
+
+    with patch("ratelimiter.core.time", side_effect=[1000.0, 1001.0, 1002.0, 1012.0]), patch(
+        "ratelimiter.decorator.time", side_effect=[1000.0, 1001.0, 1012.0]
+    ):
+        assert ping() == "pong"
+        assert ping() == "pong"
+
+        with pytest.raises(RateLimitExceeded):
+            ping()
+
+        assert ping() == "pong"
+
+
+def test_thread_safety_only_n_succeed() -> None:
+    limit = 4
+    total_threads = 10
+
+    @rate_limit(calls=limit, per=60)
+    def guarded() -> str:
+        return "ok"
+
+    barrier = threading.Barrier(total_threads)
+    results: list[str] = []
+
+    def worker() -> None:
+        barrier.wait()
+        try:
+            guarded()
+            results.append("ok")
+        except RateLimitExceeded:
+            results.append("blocked")
+
+    threads = [threading.Thread(target=worker) for _ in range(total_threads)]
+
+    with patch("ratelimiter.core.time", return_value=1000.0), patch(
+        "ratelimiter.decorator.time", return_value=1000.0
+    ):
+        for thread in threads:
+            thread.start()
+
+        for thread in threads:
+            thread.join(timeout=3)
+
+    assert all(not thread.is_alive() for thread in threads)
+    assert results.count("ok") == limit
+    assert results.count("blocked") == total_threads - limit