sheriff-limiter 0.1.0__tar.gz

sheriff_limiter-0.1.0/.gitignore

@@ -0,0 +1,141 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+bin/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Sphinx documentation
+doc/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or app, you might want to share your .python-version.
+#   Comment/uncomment to share.
+#.python-version
+
+# pipenv
+#   According to pypa/pipenv#1402, Pipfile.lock prevents deterministic
+#   builds in applications but is recommended for libraries.
+#   So, for a library you should keep it.
+#Pipfile.lock
+
+# poetry
+#   Similarly, poetry.lock should be committed for applications, but is optional/not recommended for libraries.
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, pdm.lock is usage-specific.
+#pdm.lock
+
+# PEP 582; project local packages directory (used by pdm)
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.nosetests
+/nosetests.xml
+/.pytest_cache
+.coverage
+
+# Cython debug symbols
+cython_debug/
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo

sheriff_limiter-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: sheriff-limiter
+Version: 0.1.0
+Summary: An elegant, thread-safe, in-memory rate limiter for Python
+Author-email: Vahsi Bati <info@vahsibati.com.tr>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sheriff 🤠
+
+An elegant, thread-safe, in-memory rate limiter for Python.
+
+`sheriff` implements the **Token Bucket** algorithm, ensuring complete thread-safety with fine-grained locking and zero-leak memory management. It is designed to be lightweight, dependency-free, and extremely easy to integrate into any application or web framework (like FastAPI).
+
+---
+
+## Features
+
+- 🔒 **Thread-Safe**: Uses fine-grained concurrent locks to ensure rate-limiting consistency across multiple threads.
+- 🪣 **Token Bucket Algorithm**: Standard token bucket rate limiting with lazy, high-precision token replenishment.
+- 🧹 **Self-Cleaning (Lazy Cleanup)**: Prunes stale/fully-replenished buckets from memory automatically to prevent memory leaks.
+- ⚡ **Zero Dependencies**: Pure Python, built using standard library tools.
+- 🚀 **FastAPI / Web Ready**: Fits perfectly into FastAPI's dependency injection (`Depends`) system.
+
+---
+
+## Installation
+
+Install using `pip`:
+
+```bash
+pip install sheriff-limiter
+```
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+Use `is_allowed` for a simple boolean check:
+
+```python
+from sheriff import RateLimiter
+
+# Default: 10 requests capacity, replenishes 1 token per second
+limiter = RateLimiter()
+
+# Check if allowed
+if limiter.is_allowed("user_ip_address"):
+    print("Request allowed!")
+else:
+    print("Rate limit exceeded.")
+```
+
+### Configuration Options
+
+Initialize the limiter with custom parameters:
+
+```python
+from sheriff import RateLimiter
+
+# Configured for max 100 requests per minute
+limiter = RateLimiter(max_requests=100, period=60.0)
+
+# Or set capacity and refill rate directly
+# Capacity of 5 tokens, refilling 0.5 tokens/sec
+limiter = RateLimiter(capacity=5.0, refill_rate=0.5)
+```
+
+---
+
+## Advanced Features
+
+### 1. Raising Exceptions on Exceeding Limits
+
+You can use `.check()` which raises a `RateLimitExceeded` exception. The exception contains a `retry_after` parameter telling you how long to wait in seconds.
+
+```python
+from sheriff import RateLimiter, RateLimitExceeded
+
+limiter = RateLimiter(max_requests=5, period=10.0)
+
+try:
+    # Consume 1 token
+    limiter.check("client_1")
+except RateLimitExceeded as e:
+    print(f"Rate limit exceeded! Retry after {e.retry_after:.2f} seconds.")
+```
+
+### 2. Manual Resets
+
+Clear specific keys or reset all rate limits entirely:
+
+```python
+# Reset a single client
+limiter.reset("client_1")
+
+# Reset all clients and clear the memory cache
+limiter.reset_all()
+```
+
+---
+
+## FastAPI Integration
+
+`sheriff` is perfect for FastAPI dependencies. Here is how you can use it to rate-limit endpoints by IP address:
+
+```python
+from fastapi import FastAPI, Depends, Request, HTTPException, status
+from sheriff import RateLimiter, RateLimitExceeded
+
+app = FastAPI()
+
+# 100 requests per minute limit
+limiter = RateLimiter(max_requests=100, period=60.0)
+
+def rate_limit(request: Request):
+    client_ip = request.client.host if request.client else "unknown"
+    try:
+        limiter.check(client_ip)
+    except RateLimitExceeded as e:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Too many requests. Please slow down.",
+            headers={"Retry-After": str(int(e.retry_after or 0))}
+        )
+
+@app.get("/items", dependencies=[Depends(rate_limit)])
+async def read_items():
+    return {"status": "ok"}
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

sheriff_limiter-0.1.0/README.md

@@ -0,0 +1,130 @@
+# Sheriff 🤠
+
+An elegant, thread-safe, in-memory rate limiter for Python.
+
+`sheriff` implements the **Token Bucket** algorithm, ensuring complete thread-safety with fine-grained locking and zero-leak memory management. It is designed to be lightweight, dependency-free, and extremely easy to integrate into any application or web framework (like FastAPI).
+
+---
+
+## Features
+
+- 🔒 **Thread-Safe**: Uses fine-grained concurrent locks to ensure rate-limiting consistency across multiple threads.
+- 🪣 **Token Bucket Algorithm**: Standard token bucket rate limiting with lazy, high-precision token replenishment.
+- 🧹 **Self-Cleaning (Lazy Cleanup)**: Prunes stale/fully-replenished buckets from memory automatically to prevent memory leaks.
+- ⚡ **Zero Dependencies**: Pure Python, built using standard library tools.
+- 🚀 **FastAPI / Web Ready**: Fits perfectly into FastAPI's dependency injection (`Depends`) system.
+
+---
+
+## Installation
+
+Install using `pip`:
+
+```bash
+pip install sheriff-limiter
+```
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+Use `is_allowed` for a simple boolean check:
+
+```python
+from sheriff import RateLimiter
+
+# Default: 10 requests capacity, replenishes 1 token per second
+limiter = RateLimiter()
+
+# Check if allowed
+if limiter.is_allowed("user_ip_address"):
+    print("Request allowed!")
+else:
+    print("Rate limit exceeded.")
+```
+
+### Configuration Options
+
+Initialize the limiter with custom parameters:
+
+```python
+from sheriff import RateLimiter
+
+# Configured for max 100 requests per minute
+limiter = RateLimiter(max_requests=100, period=60.0)
+
+# Or set capacity and refill rate directly
+# Capacity of 5 tokens, refilling 0.5 tokens/sec
+limiter = RateLimiter(capacity=5.0, refill_rate=0.5)
+```
+
+---
+
+## Advanced Features
+
+### 1. Raising Exceptions on Exceeding Limits
+
+You can use `.check()` which raises a `RateLimitExceeded` exception. The exception contains a `retry_after` parameter telling you how long to wait in seconds.
+
+```python
+from sheriff import RateLimiter, RateLimitExceeded
+
+limiter = RateLimiter(max_requests=5, period=10.0)
+
+try:
+    # Consume 1 token
+    limiter.check("client_1")
+except RateLimitExceeded as e:
+    print(f"Rate limit exceeded! Retry after {e.retry_after:.2f} seconds.")
+```
+
+### 2. Manual Resets
+
+Clear specific keys or reset all rate limits entirely:
+
+```python
+# Reset a single client
+limiter.reset("client_1")
+
+# Reset all clients and clear the memory cache
+limiter.reset_all()
+```
+
+---
+
+## FastAPI Integration
+
+`sheriff` is perfect for FastAPI dependencies. Here is how you can use it to rate-limit endpoints by IP address:
+
+```python
+from fastapi import FastAPI, Depends, Request, HTTPException, status
+from sheriff import RateLimiter, RateLimitExceeded
+
+app = FastAPI()
+
+# 100 requests per minute limit
+limiter = RateLimiter(max_requests=100, period=60.0)
+
+def rate_limit(request: Request):
+    client_ip = request.client.host if request.client else "unknown"
+    try:
+        limiter.check(client_ip)
+    except RateLimitExceeded as e:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Too many requests. Please slow down.",
+            headers={"Retry-After": str(int(e.retry_after or 0))}
+        )
+
+@app.get("/items", dependencies=[Depends(rate_limit)])
+async def read_items():
+    return {"status": "ok"}
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

sheriff_limiter-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sheriff-limiter"
+dynamic = ["version"]
+description = "An elegant, thread-safe, in-memory rate limiter for Python"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Vahsi Bati", email = "info@vahsibati.com.tr"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "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",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+
+[tool.hatch.version]
+path = "src/sheriff/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sheriff"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = []
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --tb=short"
+testpaths = [
+    "tests",
+]

sheriff_limiter-0.1.0/src/sheriff/__init__.py

@@ -0,0 +1,10 @@
+__version__ = "0.1.0"
+
+from sheriff.core import RateLimiter
+from sheriff.exceptions import RateLimitExceeded, SheriffError
+
+__all__ = [
+    "RateLimiter",
+    "SheriffError",
+    "RateLimitExceeded",
+]

sheriff_limiter-0.1.0/src/sheriff/core.py

@@ -0,0 +1,217 @@
+import time
+from threading import Lock
+from typing import Dict, Optional, Tuple
+
+from sheriff.exceptions import RateLimitExceeded
+
+
+class TokenBucket:
+    """Represents a single Token Bucket for rate limiting a specific key."""
+
+    def __init__(self, capacity: float, refill_rate: float):
+        self.capacity = capacity
+        self.refill_rate = refill_rate
+        self.tokens = capacity
+        self.last_updated = time.monotonic()
+        self.lock = Lock()
+
+    def consume(self, tokens: float = 1.0) -> Tuple[bool, float]:
+        """Consume tokens from the bucket.
+
+        Returns:
+            Tuple[bool, float]: (allowed, retry_after)
+            where allowed is True if consumed, False otherwise.
+            retry_after is the number of seconds to wait before there's enough tokens.
+        """
+        with self.lock:
+            now = time.monotonic()
+            elapsed = now - self.last_updated
+            if elapsed > 0:
+                self.tokens = min(
+                    self.capacity, self.tokens + elapsed * self.refill_rate
+                )
+                self.last_updated = now
+
+            if self.tokens >= tokens:
+                self.tokens -= tokens
+                return True, 0.0
+
+            needed = tokens - self.tokens
+            retry_after = needed / self.refill_rate
+            return False, retry_after
+
+    def get_tokens(self) -> float:
+        """Returns the current number of tokens in the bucket after replenishment."""
+        with self.lock:
+            now = time.monotonic()
+            elapsed = now - self.last_updated
+            if elapsed > 0:
+                self.tokens = min(
+                    self.capacity, self.tokens + elapsed * self.refill_rate
+                )
+                self.last_updated = now
+            return self.tokens
+
+    def reset(self) -> None:
+        """Resets the bucket to its full capacity."""
+        with self.lock:
+            self.tokens = self.capacity
+            self.last_updated = time.monotonic()
+
+    def is_full(self, now: float) -> bool:
+        """Check if the bucket is fully replenished.
+        Must be called under RateLimiter container lock or self.lock.
+        """
+        with self.lock:
+            elapsed = now - self.last_updated
+            current_tokens = min(
+                self.capacity, self.tokens + elapsed * self.refill_rate
+            )
+            return current_tokens >= self.capacity
+
+
+class RateLimiter:
+    """Core class representing the Sheriff thread-safe, in-memory rate limiter."""
+
+    def __init__(
+        self,
+        capacity: float = 10.0,
+        refill_rate: float = 1.0,
+        max_requests: Optional[int] = None,
+        period: Optional[float] = None,
+        cleanup_interval: float = 60.0,
+    ):
+        """Initializes the RateLimiter.
+
+        Args:
+            capacity: Maximum number of tokens a bucket can hold. Defaults to 10.0.
+            refill_rate: Number of tokens added to the bucket per second.
+                Defaults to 1.0.
+            max_requests: Optional parameter to initialize capacity using requests.
+            period: Optional parameter to specify the period in seconds for
+                max_requests.
+            cleanup_interval: Time in seconds between periodic cleanup sweeps of
+                fully replenished buckets. Defaults to 60.0.
+        """
+        if max_requests is not None:
+            capacity = float(max_requests)
+            if period is not None:
+                refill_rate = capacity / period
+            else:
+                refill_rate = capacity
+
+        if capacity <= 0:
+            raise ValueError("Capacity must be greater than zero.")
+        if refill_rate <= 0:
+            raise ValueError("Refill rate must be greater than zero.")
+        if cleanup_interval <= 0:
+            raise ValueError("Cleanup interval must be greater than zero.")
+
+        self.capacity = capacity
+        self.refill_rate = refill_rate
+        self.cleanup_interval = cleanup_interval
+
+        self.buckets: Dict[str, TokenBucket] = {}
+        self.lock = Lock()
+        self.last_cleanup = time.monotonic()
+
+    def _get_bucket(self, key: str) -> TokenBucket:
+        """Thread-safe retrieval or creation of a TokenBucket for a given key.
+        Also triggers lazy cleanup if the cleanup interval has elapsed.
+        """
+        with self.lock:
+            self._maybe_cleanup()
+            if key not in self.buckets:
+                self.buckets[key] = TokenBucket(self.capacity, self.refill_rate)
+            return self.buckets[key]
+
+    def _maybe_cleanup(self) -> None:
+        """Prunes fully replenished buckets from memory.
+        Must be called with self.lock held.
+        """
+        now = time.monotonic()
+        if now - self.last_cleanup >= self.cleanup_interval:
+            keys_to_delete = []
+            for key, bucket in self.buckets.items():
+                if bucket.is_full(now):
+                    keys_to_delete.append(key)
+            for key in keys_to_delete:
+                del self.buckets[key]
+            self.last_cleanup = now
+
+    def is_allowed(self, key: str, tokens: float = 1.0) -> bool:
+        """Check if the request is allowed under the rate limit.
+
+        Args:
+            key: Unique identifier for the client or bucket.
+            tokens: Number of tokens to consume. Defaults to 1.0.
+
+        Returns:
+            bool: True if the request is allowed, False otherwise.
+        """
+        bucket = self._get_bucket(key)
+        allowed, _ = bucket.consume(tokens)
+        return allowed
+
+    def check(self, key: str, tokens: float = 1.0) -> None:
+        """Check if the request is allowed under the rate limit.
+        Raises RateLimitExceeded if not.
+
+        Args:
+            key: Unique identifier for the client or bucket.
+            tokens: Number of tokens to consume. Defaults to 1.0.
+
+        Raises:
+            RateLimitExceeded: If the key is rate-limited.
+        """
+        bucket = self._get_bucket(key)
+        allowed, retry_after = bucket.consume(tokens)
+        if not allowed:
+            raise RateLimitExceeded(
+                message=f"Rate limit exceeded for key: {key}",
+                retry_after=retry_after,
+            )
+
+    def consume(self, key: str, tokens: float = 1.0) -> Tuple[bool, float]:
+        """Consume tokens from the bucket for the given key.
+
+        Args:
+            key: Unique identifier for the client or bucket.
+            tokens: Number of tokens to consume. Defaults to 1.0.
+
+        Returns:
+            Tuple[bool, float]: (allowed, retry_after)
+                where allowed is True if consumed, False otherwise.
+                retry_after is the number of seconds to wait before there are
+                enough tokens.
+        """
+        bucket = self._get_bucket(key)
+        return bucket.consume(tokens)
+
+    def get_tokens(self, key: str) -> float:
+        """Returns the current number of tokens available in the bucket for the key.
+
+        Args:
+            key: Unique identifier for the client or bucket.
+
+        Returns:
+            float: Current number of tokens.
+        """
+        bucket = self._get_bucket(key)
+        return bucket.get_tokens()
+
+    def reset(self, key: str) -> None:
+        """Reset the rate limit bucket for the given key.
+
+        Args:
+            key: Unique identifier for the client or bucket.
+        """
+        with self.lock:
+            bucket = self.buckets.get(key)
+            if bucket is not None:
+                bucket.reset()
+
+    def reset_all(self) -> None:
+        """Reset all rate limit buckets, clearing the internal cache."""
+        with self.lock:
+            self.buckets.clear()

sheriff_limiter-0.1.0/src/sheriff/exceptions.py

@@ -0,0 +1,19 @@
+from typing import Optional
+
+
+class SheriffError(Exception):
+    """Base exception for all Sheriff rate limiter errors."""
+
+    pass
+
+
+class RateLimitExceeded(SheriffError):
+    """Exception raised when a rate limit is exceeded."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[float] = None,
+    ):
+        super().__init__(message)
+        self.retry_after = retry_after

sheriff_limiter-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+# Test suite for sheriff rate limiter

sheriff_limiter-0.1.0/tests/conftest.py

@@ -0,0 +1,9 @@
+import pytest
+
+from sheriff.core import RateLimiter
+
+
+@pytest.fixture
+def limiter():
+    """Returns a basic RateLimiter instance."""
+    return RateLimiter()

sheriff_limiter-0.1.0/tests/test_limiter.py

@@ -0,0 +1,193 @@
+import threading
+import time
+from unittest.mock import patch
+
+import pytest
+
+from sheriff.core import RateLimiter
+from sheriff.exceptions import RateLimitExceeded
+
+
+def test_limiter_creation_defaults(limiter):
+    assert isinstance(limiter, RateLimiter)
+    assert limiter.capacity == 10.0
+    assert limiter.refill_rate == 1.0
+    assert limiter.cleanup_interval == 60.0
+
+
+def test_limiter_creation_custom():
+    limiter = RateLimiter(capacity=20.0, refill_rate=2.5, cleanup_interval=30.0)
+    assert limiter.capacity == 20.0
+    assert limiter.refill_rate == 2.5
+    assert limiter.cleanup_interval == 30.0
+
+
+def test_limiter_creation_max_requests():
+    limiter = RateLimiter(max_requests=100, period=60.0)
+    assert limiter.capacity == 100.0
+    assert limiter.refill_rate == 100.0 / 60.0
+
+
+def test_limiter_creation_max_requests_no_period():
+    limiter = RateLimiter(max_requests=50)
+    assert limiter.capacity == 50.0
+    assert limiter.refill_rate == 50.0
+
+
+def test_invalid_parameters():
+    with pytest.raises(ValueError, match="Capacity must be greater than zero"):
+        RateLimiter(capacity=0)
+    with pytest.raises(ValueError, match="Capacity must be greater than zero"):
+        RateLimiter(capacity=-10)
+    with pytest.raises(ValueError, match="Refill rate must be greater than zero"):
+        RateLimiter(refill_rate=0)
+    with pytest.raises(ValueError, match="Refill rate must be greater than zero"):
+        RateLimiter(refill_rate=-1)
+    with pytest.raises(ValueError, match="Cleanup interval must be greater than zero"):
+        RateLimiter(cleanup_interval=0)
+    with pytest.raises(ValueError, match="Cleanup interval must be greater than zero"):
+        RateLimiter(cleanup_interval=-5)
+
+
+def test_is_allowed_basic():
+    limiter = RateLimiter(capacity=3.0, refill_rate=1.0)
+
+    assert limiter.is_allowed("user-1", tokens=1.0) is True
+    assert limiter.is_allowed("user-1", tokens=2.0) is True
+    # Now empty
+    assert limiter.is_allowed("user-1", tokens=1.0) is False
+
+
+def test_token_replenishment():
+    limiter = RateLimiter(capacity=5.0, refill_rate=2.0)
+
+    start_time = 100.0
+    with patch("time.monotonic", return_value=start_time):
+        assert limiter.is_allowed("user-2", tokens=5.0) is True
+        assert limiter.is_allowed("user-2", tokens=1.0) is False
+
+    # After 1.5 seconds, we should replenish 1.5 * 2 = 3.0 tokens
+    with patch("time.monotonic", return_value=start_time + 1.5):
+        assert limiter.is_allowed("user-2", tokens=3.0) is True
+        assert limiter.is_allowed("user-2", tokens=1.0) is False
+
+    # After another 2.5 seconds, we should replenish up to capacity (max 5)
+    with patch("time.monotonic", return_value=start_time + 4.0):
+        assert limiter.is_allowed("user-2", tokens=5.0) is True
+        assert limiter.is_allowed("user-2", tokens=1.0) is False
+
+
+def test_check_raises_exception():
+    limiter = RateLimiter(capacity=2.0, refill_rate=1.0)
+
+    start_time = 100.0
+    with patch("time.monotonic", return_value=start_time):
+        limiter.check("user-3", tokens=2.0)
+
+        with pytest.raises(RateLimitExceeded) as exc_info:
+            limiter.check("user-3", tokens=1.0)
+
+        assert exc_info.value.retry_after == 1.0
+
+        # If we need 2 tokens, it will require 2 seconds
+        with pytest.raises(RateLimitExceeded) as exc_info2:
+            limiter.check("user-3", tokens=2.0)
+
+        assert exc_info2.value.retry_after == 2.0
+
+
+def test_consume_returns_tuple():
+    limiter = RateLimiter(capacity=2.0, refill_rate=0.5)
+
+    start_time = 100.0
+    with patch("time.monotonic", return_value=start_time):
+        allowed, retry_after = limiter.consume("user-4", tokens=1.5)
+        assert allowed is True
+        assert retry_after == 0.0
+
+        allowed, retry_after = limiter.consume("user-4", tokens=1.0)
+        assert allowed is False
+        # Needs 1.0 - 0.5 = 0.5 tokens. At refill_rate 0.5, needs 1.0 second.
+        assert retry_after == 1.0
+
+
+def test_get_tokens():
+    limiter = RateLimiter(capacity=10.0, refill_rate=2.0)
+
+    start_time = 100.0
+    with patch("time.monotonic", return_value=start_time):
+        assert limiter.get_tokens("user-5") == 10.0
+        assert limiter.is_allowed("user-5", tokens=4.0) is True
+        assert limiter.get_tokens("user-5") == 6.0
+
+    with patch("time.monotonic", return_value=start_time + 1.5):
+        # 6.0 + 1.5 * 2 = 9.0
+        assert limiter.get_tokens("user-5") == 9.0
+
+
+def test_reset_and_reset_all():
+    limiter = RateLimiter(capacity=5.0, refill_rate=1.0)
+
+    limiter.is_allowed("user-a", tokens=5.0)
+    limiter.is_allowed("user-b", tokens=5.0)
+
+    assert limiter.is_allowed("user-a", tokens=1.0) is False
+    assert limiter.is_allowed("user-b", tokens=1.0) is False
+
+    limiter.reset("user-a")
+    assert limiter.is_allowed("user-a", tokens=5.0) is True
+    assert limiter.is_allowed("user-b", tokens=1.0) is False
+
+    limiter.is_allowed("user-a", tokens=5.0)
+    limiter.reset_all()
+    assert limiter.is_allowed("user-a", tokens=5.0) is True
+    assert limiter.is_allowed("user-b", tokens=5.0) is True
+
+
+def test_lazy_cleanup():
+    limiter = RateLimiter(capacity=5.0, refill_rate=1.0, cleanup_interval=0.1)
+
+    # Access a key to create a bucket
+    assert limiter.is_allowed("key1", tokens=1.0) is True
+    assert "key1" in limiter.buckets
+
+    # Wait, but not long enough to fully replenish
+    time.sleep(0.15)
+
+    # Access key2 to trigger cleanup check
+    assert limiter.is_allowed("key2", tokens=1.0) is True
+    # key1 is not fully replenished, so it shouldn't be deleted
+    assert "key1" in limiter.buckets
+
+    # Wait long enough to fully replenish key1 (needs 1.0 second to recover 1.0 token)
+    time.sleep(1.0)
+
+    # Access key2 to trigger cleanup
+    assert limiter.is_allowed("key2", tokens=1.0) is True
+    # key1 is now fully replenished, so it should be deleted
+    assert "key1" not in limiter.buckets
+
+
+def test_concurrent_consumption():
+    # Thread safety check: Ensure no double-consumption
+    limiter = RateLimiter(capacity=50.0, refill_rate=0.0001)
+
+    successes = [0]
+    lock = threading.Lock()
+
+    def worker():
+        for _ in range(10):
+            if limiter.is_allowed("concurrent-key", tokens=1.0):
+                with lock:
+                    successes[0] += 1
+
+    threads = [threading.Thread(target=worker) for _ in range(10)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    # With 10 threads doing 10 attempts each, total 100 attempts,
+    # but capacity is 50 and refill rate is negligible.
+    # Therefore, exactly 50 should succeed.
+    assert successes[0] == 50