fastapi-concurrency-limiter 0.1.0__tar.gz

fastapi_concurrency_limiter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Zilahi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_concurrency_limiter-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: fastapi-concurrency-limiter
+Version: 0.1.0
+Summary: Semaphore-based concurrency limiter for FastAPI
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,concurrency,semaphore,rate-limiting,async
+Author: David Zilahi
+Author-email: zilahia@gmail.com
+Requires-Python: >=3.12
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Typing :: Typed
+Requires-Dist: fastapi (>=0.100.0)
+Description-Content-Type: text/markdown
+
+# fastapi-concurrency-limiter
+
+Semaphore-based concurrency limiter for [FastAPI](https://fastapi.tiangolo.com/). Define named resources with a maximum concurrency, apply them to routes with a decorator, and get automatic 503 responses when the server is too busy.
+
+## Installation
+
+```bash
+pip install fastapi-concurrency-limiter
+```
+
+## Usage
+
+```python
+from fastapi import FastAPI
+from fastapi_concurrency_limiter import Limiter, Resource
+
+app = FastAPI()
+
+database_resource = Resource(5)   # max 5 concurrent DB operations
+file_resource = Resource(10)      # max 10 concurrent file operations
+
+# Register resources with the limiter in the order they should be acquired.
+# Always use this same order in @limiter.resources() to prevent deadlocks.
+limiter = Limiter(timeout=5, resources=[database_resource, file_resource])
+
+
+@app.get("/messages")
+@limiter.resources([database_resource])
+async def read_messages():
+    ...
+
+
+@app.get("/file")
+@limiter.resources([file_resource])
+async def read_file():
+    ...
+
+
+@app.get("/messages-and-file")
+@limiter.resources([database_resource, file_resource])  # must match registration order
+async def read_messages_and_file():
+    ...
+```
+
+When a request cannot acquire a semaphore within `timeout` seconds it receives:
+
+```json
+{"detail": "Server busy, please retry later"}
+```
+
+with HTTP status **503**.
+
+## Resource ordering and deadlocks
+
+When an endpoint acquires multiple resources, always pass them to `@limiter.resources()` in the same order they were registered in `Limiter(resources=[...])`. Passing them in a different order raises a `ValueError` at startup — this is intentional: consistent acquisition order is the simplest way to prevent deadlocks.
+
+```python
+limiter = Limiter(timeout=5, resources=[db, fs])
+
+@app.get("/ok")
+@limiter.resources([db, fs])   # correct
+async def ok(): ...
+
+@app.get("/bad")
+@limiter.resources([fs, db])   # raises ValueError at startup
+async def bad(): ...
+```
+
+## API
+
+### `Resource(capacity: int)`
+
+A semaphore with the given concurrency limit.
+
+### `Limiter(timeout: float, resources: list[Resource])`
+
+- `timeout` — seconds to wait for semaphore acquisition before returning 503.
+- `resources` — all resources managed by this limiter, in canonical acquisition order.
+
+### `@limiter.resources(resources: list[Resource])`
+
+Route decorator. Acquires the listed resources before the handler runs and releases them after, even on exception.
+
+## License
+
+MIT
+

fastapi_concurrency_limiter-0.1.0/README.md

@@ -0,0 +1,86 @@
+# fastapi-concurrency-limiter
+
+Semaphore-based concurrency limiter for [FastAPI](https://fastapi.tiangolo.com/). Define named resources with a maximum concurrency, apply them to routes with a decorator, and get automatic 503 responses when the server is too busy.
+
+## Installation
+
+```bash
+pip install fastapi-concurrency-limiter
+```
+
+## Usage
+
+```python
+from fastapi import FastAPI
+from fastapi_concurrency_limiter import Limiter, Resource
+
+app = FastAPI()
+
+database_resource = Resource(5)   # max 5 concurrent DB operations
+file_resource = Resource(10)      # max 10 concurrent file operations
+
+# Register resources with the limiter in the order they should be acquired.
+# Always use this same order in @limiter.resources() to prevent deadlocks.
+limiter = Limiter(timeout=5, resources=[database_resource, file_resource])
+
+
+@app.get("/messages")
+@limiter.resources([database_resource])
+async def read_messages():
+    ...
+
+
+@app.get("/file")
+@limiter.resources([file_resource])
+async def read_file():
+    ...
+
+
+@app.get("/messages-and-file")
+@limiter.resources([database_resource, file_resource])  # must match registration order
+async def read_messages_and_file():
+    ...
+```
+
+When a request cannot acquire a semaphore within `timeout` seconds it receives:
+
+```json
+{"detail": "Server busy, please retry later"}
+```
+
+with HTTP status **503**.
+
+## Resource ordering and deadlocks
+
+When an endpoint acquires multiple resources, always pass them to `@limiter.resources()` in the same order they were registered in `Limiter(resources=[...])`. Passing them in a different order raises a `ValueError` at startup — this is intentional: consistent acquisition order is the simplest way to prevent deadlocks.
+
+```python
+limiter = Limiter(timeout=5, resources=[db, fs])
+
+@app.get("/ok")
+@limiter.resources([db, fs])   # correct
+async def ok(): ...
+
+@app.get("/bad")
+@limiter.resources([fs, db])   # raises ValueError at startup
+async def bad(): ...
+```
+
+## API
+
+### `Resource(capacity: int)`
+
+A semaphore with the given concurrency limit.
+
+### `Limiter(timeout: float, resources: list[Resource])`
+
+- `timeout` — seconds to wait for semaphore acquisition before returning 503.
+- `resources` — all resources managed by this limiter, in canonical acquisition order.
+
+### `@limiter.resources(resources: list[Resource])`
+
+Route decorator. Acquires the listed resources before the handler runs and releases them after, even on exception.
+
+## License
+
+MIT

fastapi_concurrency_limiter-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "fastapi-concurrency-limiter"
+version = "0.1.0"
+description = "Semaphore-based concurrency limiter for FastAPI"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "David Zilahi", email = "zilahia@gmail.com"}]
+keywords = ["fastapi", "concurrency", "semaphore", "rate-limiting", "async"]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.100.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: FastAPI",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Typing :: Typed",
+]
+
+[tool.poetry]
+packages = [{include = "fastapi_concurrency_limiter", from = "src"}]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4"
+pytest-asyncio = "^0.23"
+httpx = "^0.26"
+uvicorn = "^0.29"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

fastapi_concurrency_limiter-0.1.0/src/fastapi_concurrency_limiter/__init__.py

@@ -0,0 +1,4 @@
+from .limiter import Limiter
+from .resource import Resource
+
+__all__ = ["Limiter", "Resource"]

fastapi_concurrency_limiter-0.1.0/src/fastapi_concurrency_limiter/limiter.py

@@ -0,0 +1,56 @@
+import asyncio
+import functools
+import inspect
+from contextlib import asynccontextmanager
+from typing import Callable
+
+from fastapi import HTTPException
+
+from .resource import Resource
+
+
+class Limiter:
+    def __init__(self, timeout: float, resources: list[Resource]) -> None:
+        self.timeout = timeout
+        self._resources = resources
+
+    def resources(self, resources: list[Resource]) -> Callable:
+        for r in resources:
+            if r not in self._resources:
+                raise ValueError(f"Resource {r!r} was not registered with this Limiter")
+
+        positions = [self._resources.index(r) for r in resources]
+        if positions != sorted(positions):
+            raise ValueError(
+                "Resources must be passed in registration order to prevent deadlocks"
+            )
+
+        def decorator(func: Callable) -> Callable:
+            @functools.wraps(func)
+            async def wrapper(*args, **kwargs):
+                async with self._acquire_all(resources):
+                    return await func(*args, **kwargs)
+
+            wrapper.__signature__ = inspect.signature(func)
+            return wrapper
+
+        return decorator
+
+    @asynccontextmanager
+    async def _acquire_all(self, resources: list[Resource]):
+        acquired: list[Resource] = []
+        try:
+            try:
+                async with asyncio.timeout(self.timeout):
+                    for resource in resources:
+                        await resource._semaphore.acquire()
+                        acquired.append(resource)
+            except TimeoutError:
+                raise HTTPException(
+                    status_code=503,
+                    detail="Server busy, please retry later",
+                )
+            yield
+        finally:
+            for resource in reversed(acquired):
+                resource._semaphore.release()

fastapi_concurrency_limiter-0.1.0/src/fastapi_concurrency_limiter/resource.py

@@ -0,0 +1,9 @@
+import asyncio
+
+
+class Resource:
+    def __init__(self, capacity: int) -> None:
+        if capacity < 1:
+            raise ValueError("capacity must be >= 1")
+        self.capacity = capacity
+        self._semaphore = asyncio.Semaphore(capacity)