fastapi-file-validator 0.0.0__tar.gz → 0.0.2__tar.gz

fastapi_file_validator-0.0.2/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: fastapi-file-validator
+Version: 0.0.2
+Summary: A lightweight, flexible file extension validator and MIME type checker for fastapi
+Author-email: Seungkyu-Han <trust1204@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Seungkyu-Han/fastapi-file-validator
+Project-URL: Bug Tracker, https://github.com/Seungkyu-Han/fastapi-file-validator
+Project-URL: Documentation, https://github.com/Seungkyu-Han/fastapi-file-validator
+Project-URL: Source, https://github.com/Seungkyu-Han/fastapi-file-validator
+Keywords: validator
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.1
+
+# FastAPI File Validators
+
+A simple, lightweight, and flexible decorator-based file validation library for FastAPI. Easily validate uploaded file extensions and file sizes before hitting your endpoint logic.
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+[![codecov](https://codecov.io/gh/Seungkyu-Han/fastapi-file-validator/graph/badge.svg?token=VQMH5631MD)](https://codecov.io/gh/Seungkyu-Han/fastapi-file-validator)
+[![PyPI downloads](https://img.shields.io/pypi/dm/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+[![license](https://img.shields.io/pypi/l/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+
+
+
+---
+
+## 🚀 Installation
+
+Install via pip:
+
+```bash
+pip install fastapi-file-validators
+
+```
+
+Or install locally for development:
+
+```bash
+pip install -e .
+
+```
+
+---
+
+## 📦 Usage
+
+### 1. Validate File Extension
+
+Ensure that the uploaded file matches specific allowed extensions. If the extension is invalid or missing, it automatically raises an `HTTP 415 Unsupported Media Type` or `HTTP 400 Bad Request`.
+
+```python
+from fastapi import FastAPI, UploadFile, File
+from file_validator import file_extension_validator
+
+app = FastAPI()
+
+@app.post("/upload/image")
+@file_extension_validator(file_arg_name="file", file_extensions={"jpg", "jpeg", "png"})
+async def upload_image(file: UploadFile = File(...)):
+    return {"filename": file.filename, "message": "Extension validated successfully!"}
+
+```
+
+---
+
+### 2. Validate File Size
+
+Restrict the maximum size of an uploaded file in Megabytes (MB). If the file exceeds the limit, it automatically raises an `HTTP 413 Content Too Large`.
+
+```python
+from fastapi import FastAPI, UploadFile, File
+from file_validator import file_size_validator
+
+app = FastAPI()
+
+@app.post("/upload/large-file")
+@file_size_validator(file_arg_name="file", max_size_mb=10)  # Limit to 10MB
+async def upload_large_file(file: UploadFile = File(...)):
+    return {"size": file.size, "message": "Size validated successfully!"}
+
+```
+
+---
+
+## ⚙️ Configuration
+
+### Exception Handling
+
+The decorators raise standard FastAPI `HTTPException`s. You can expect the following responses when validation fails:
+
+| Validator | Scenario | HTTP Status | Detail Message Example |
+| --- | --- | --- | --- |
+| `file_extension_validator` | Filename is empty | `400 Bad Request` | `"filename is empty"` |
+| `file_extension_validator` | Invalid extension | `415 Unsupported Media Type` | `"exe type is unavailable"` |
+| `file_size_validator` | File exceeds max size | `413 Content Too Large` | `"file size is bigger than 5MB"` |
+
+---
+
+## 📄 License
+
+MIT License

fastapi_file_validator-0.0.2/README.md

@@ -0,0 +1,88 @@
+# FastAPI File Validators
+
+A simple, lightweight, and flexible decorator-based file validation library for FastAPI. Easily validate uploaded file extensions and file sizes before hitting your endpoint logic.
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+[![codecov](https://codecov.io/gh/Seungkyu-Han/fastapi-file-validator/graph/badge.svg?token=VQMH5631MD)](https://codecov.io/gh/Seungkyu-Han/fastapi-file-validator)
+[![PyPI downloads](https://img.shields.io/pypi/dm/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+[![license](https://img.shields.io/pypi/l/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+
+
+
+---
+
+## 🚀 Installation
+
+Install via pip:
+
+```bash
+pip install fastapi-file-validators
+
+```
+
+Or install locally for development:
+
+```bash
+pip install -e .
+
+```
+
+---
+
+## 📦 Usage
+
+### 1. Validate File Extension
+
+Ensure that the uploaded file matches specific allowed extensions. If the extension is invalid or missing, it automatically raises an `HTTP 415 Unsupported Media Type` or `HTTP 400 Bad Request`.
+
+```python
+from fastapi import FastAPI, UploadFile, File
+from file_validator import file_extension_validator
+
+app = FastAPI()
+
+@app.post("/upload/image")
+@file_extension_validator(file_arg_name="file", file_extensions={"jpg", "jpeg", "png"})
+async def upload_image(file: UploadFile = File(...)):
+    return {"filename": file.filename, "message": "Extension validated successfully!"}
+
+```
+
+---
+
+### 2. Validate File Size
+
+Restrict the maximum size of an uploaded file in Megabytes (MB). If the file exceeds the limit, it automatically raises an `HTTP 413 Content Too Large`.
+
+```python
+from fastapi import FastAPI, UploadFile, File
+from file_validator import file_size_validator
+
+app = FastAPI()
+
+@app.post("/upload/large-file")
+@file_size_validator(file_arg_name="file", max_size_mb=10)  # Limit to 10MB
+async def upload_large_file(file: UploadFile = File(...)):
+    return {"size": file.size, "message": "Size validated successfully!"}
+
+```
+
+---
+
+## ⚙️ Configuration
+
+### Exception Handling
+
+The decorators raise standard FastAPI `HTTPException`s. You can expect the following responses when validation fails:
+
+| Validator | Scenario | HTTP Status | Detail Message Example |
+| --- | --- | --- | --- |
+| `file_extension_validator` | Filename is empty | `400 Bad Request` | `"filename is empty"` |
+| `file_extension_validator` | Invalid extension | `415 Unsupported Media Type` | `"exe type is unavailable"` |
+| `file_size_validator` | File exceeds max size | `413 Content Too Large` | `"file size is bigger than 5MB"` |
+
+---
+
+## 📄 License
+
+MIT License

fastapi_file_validator-0.0.2/fastapi_file_validator.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: fastapi-file-validator
+Version: 0.0.2
+Summary: A lightweight, flexible file extension validator and MIME type checker for fastapi
+Author-email: Seungkyu-Han <trust1204@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Seungkyu-Han/fastapi-file-validator
+Project-URL: Bug Tracker, https://github.com/Seungkyu-Han/fastapi-file-validator
+Project-URL: Documentation, https://github.com/Seungkyu-Han/fastapi-file-validator
+Project-URL: Source, https://github.com/Seungkyu-Han/fastapi-file-validator
+Keywords: validator
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.1
+
+# FastAPI File Validators
+
+A simple, lightweight, and flexible decorator-based file validation library for FastAPI. Easily validate uploaded file extensions and file sizes before hitting your endpoint logic.
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+[![codecov](https://codecov.io/gh/Seungkyu-Han/fastapi-file-validator/graph/badge.svg?token=VQMH5631MD)](https://codecov.io/gh/Seungkyu-Han/fastapi-file-validator)
+[![PyPI downloads](https://img.shields.io/pypi/dm/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+[![license](https://img.shields.io/pypi/l/fastapi-file-validator)](https://pypi.org/project/fastapi-file-validator/)
+
+
+
+---
+
+## 🚀 Installation
+
+Install via pip:
+
+```bash
+pip install fastapi-file-validators
+
+```
+
+Or install locally for development:
+
+```bash
+pip install -e .
+
+```
+
+---
+
+## 📦 Usage
+
+### 1. Validate File Extension
+
+Ensure that the uploaded file matches specific allowed extensions. If the extension is invalid or missing, it automatically raises an `HTTP 415 Unsupported Media Type` or `HTTP 400 Bad Request`.
+
+```python
+from fastapi import FastAPI, UploadFile, File
+from file_validator import file_extension_validator
+
+app = FastAPI()
+
+@app.post("/upload/image")
+@file_extension_validator(file_arg_name="file", file_extensions={"jpg", "jpeg", "png"})
+async def upload_image(file: UploadFile = File(...)):
+    return {"filename": file.filename, "message": "Extension validated successfully!"}
+
+```
+
+---
+
+### 2. Validate File Size
+
+Restrict the maximum size of an uploaded file in Megabytes (MB). If the file exceeds the limit, it automatically raises an `HTTP 413 Content Too Large`.
+
+```python
+from fastapi import FastAPI, UploadFile, File
+from file_validator import file_size_validator
+
+app = FastAPI()
+
+@app.post("/upload/large-file")
+@file_size_validator(file_arg_name="file", max_size_mb=10)  # Limit to 10MB
+async def upload_large_file(file: UploadFile = File(...)):
+    return {"size": file.size, "message": "Size validated successfully!"}
+
+```
+
+---
+
+## ⚙️ Configuration
+
+### Exception Handling
+
+The decorators raise standard FastAPI `HTTPException`s. You can expect the following responses when validation fails:
+
+| Validator | Scenario | HTTP Status | Detail Message Example |
+| --- | --- | --- | --- |
+| `file_extension_validator` | Filename is empty | `400 Bad Request` | `"filename is empty"` |
+| `file_extension_validator` | Invalid extension | `415 Unsupported Media Type` | `"exe type is unavailable"` |
+| `file_size_validator` | File exceeds max size | `413 Content Too Large` | `"file size is bigger than 5MB"` |
+
+---
+
+## 📄 License
+
+MIT License

{fastapi_file_validator-0.0.0 → fastapi_file_validator-0.0.2}/fastapi_file_validator.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+README.md
 pyproject.toml
 fastapi_file_validator.egg-info/PKG-INFO
 fastapi_file_validator.egg-info/SOURCES.txt
@@ -6,4 +7,6 @@ fastapi_file_validator.egg-info/requires.txt
 fastapi_file_validator.egg-info/top_level.txt
 file_validator/__init__.py
 file_validator/file_extension_validator.py
-file_validator/file_size_validator.py
+file_validator/file_size_validator.py
+tests/test_file_extension_validator.py
+tests/test_file_size_validator.py

fastapi_file_validator-0.0.2/file_validator/file_extension_validator.py

@@ -0,0 +1,47 @@
+import os
+from functools import wraps
+
+from fastapi import HTTPException, status
+
+
+def file_extension_validator(file_arg_name: str, file_extensions: set[str]):
+    """
+    A decorator that validates the file extension of an uploaded file. Ensures that the provided file has an allowed
+    extension before executing the decorated function. Raises an HTTPException if the validation fails.
+
+    :param file_arg_name: The name of the argument in the decorated function's signature that is expected to
+        contain the file object.
+    :param file_extensions: A set of allowed file extensions (case-insensitive) for the uploaded file.
+    :return: The decorated function with added file extension validation logic.
+    :rtype: Callable
+    """
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            if file_arg_name in kwargs:
+                file = kwargs.get(file_arg_name)
+                if file and (hasattr(file, "filename")):
+
+                    filename: str | None = file.filename
+
+                    if not filename:
+                        raise HTTPException(
+                            status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=f"filename is empty",
+                        )
+
+                    _, ext = os.path.splitext(filename)
+
+                    file_extension = ext[1:].lower()
+
+                    if file_extension not in file_extensions:
+                        raise HTTPException(
+                            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+                            detail=f"{file_extension} type is unavailable",
+                        )
+
+            return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

fastapi_file_validator-0.0.2/file_validator/file_size_validator.py

@@ -0,0 +1,41 @@
+from functools import wraps
+
+from fastapi import HTTPException, status
+
+
+def file_size_validator(file_arg_name: str, max_size_mb: int):
+    """
+    Decorator to validate the size of a file passed as a keyword argument to an asynchronous function. The decorator
+    checks if the file's size exceeds the specified maximum size in megabytes and raises an HTTPException if the
+    limit is exceeded.
+
+    :param file_arg_name: The name of the keyword argument representing the file in the decorated function.
+    :param max_size_mb: The maximum file size allowed in megabytes.
+    :return: A decorator function that validates the file's size against the specified limit.
+    :rtype: Callable
+    """
+    max_size_bytes = max_size_mb * 1024 * 1024
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            if file_arg_name in kwargs:
+                file = kwargs.get(file_arg_name)
+
+                if file and (hasattr(file, "size")):
+                    file_size: int | None = file.size
+
+                    if not file_size:
+                        return await func(*args, **kwargs)
+
+                    if file_size > max_size_bytes:
+                        raise HTTPException(
+                            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
+                            detail=f"file size is bigger than {max_size_mb}MB",
+                        )
+
+            return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

{fastapi_file_validator-0.0.0 → fastapi_file_validator-0.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-file-validator"
-version = "0.0.0"
+version = "0.0.2"
 description = "A lightweight, flexible file extension validator and MIME type checker for fastapi"
 readme = "README.md"
 requires-python = ">=3.10"

fastapi_file_validator-0.0.2/tests/test_file_extension_validator.py

@@ -0,0 +1,71 @@
+from typing import Any
+
+import pytest
+from fastapi import HTTPException, status
+from unittest.mock import Mock
+
+from file_validator import file_extension_validator
+
+
+@file_extension_validator(
+    file_arg_name="file",
+    file_extensions={"jpg", "png"},
+)
+async def dummy_endpoint(file: Any):
+    return "success"
+
+
+@pytest.mark.asyncio
+async def test_file_extension_validator_success():
+    # given
+    mocked_file = Mock()
+    mocked_file.filename = "image.png"
+
+    # when
+    result = await dummy_endpoint(file=mocked_file)
+
+    # then
+    assert result == "success"
+
+
+@pytest.mark.asyncio
+async def test_file_extension_validator_case_insensitive():
+    # given
+    mocked_file = Mock()
+    mocked_file.filename = "IMAGE.JPG"
+
+    # when
+    result = await dummy_endpoint(file=mocked_file)
+
+    # then
+    assert result == "success"
+
+
+@pytest.mark.asyncio
+async def test_file_extension_validator_empty_filename():
+    # given
+    mocked_file = Mock()
+    mocked_file.filename = ""
+
+    # when
+    with pytest.raises(HTTPException) as exc_info:
+        await dummy_endpoint(file=mocked_file)
+
+    # then
+    assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
+    assert exc_info.value.detail == "filename is empty"
+
+
+@pytest.mark.asyncio
+async def test_file_extension_validator_unsupported_type():
+    # given
+    mocked_file = Mock()
+    mocked_file.filename = "document.pdf"
+
+    # when
+    with pytest.raises(HTTPException) as exc_info:
+        await dummy_endpoint(file=mocked_file)
+
+    # then
+    assert exc_info.value.status_code == status.HTTP_415_UNSUPPORTED_MEDIA_TYPE
+    assert exc_info.value.detail == "pdf type is unavailable"

fastapi_file_validator-0.0.2/tests/test_file_size_validator.py

@@ -0,0 +1,85 @@
+from typing import Any
+
+import pytest
+from fastapi import HTTPException, status
+from unittest.mock import Mock
+
+from file_validator import file_size_validator
+
+
+@file_size_validator(
+    file_arg_name="file",
+    max_size_mb=2,
+)
+async def dummy_endpoint(file: Any):
+    return "success"
+
+
+@pytest.mark.asyncio
+async def test_file_size_validator_success():
+    # given
+    mocked_file = Mock()
+    mocked_file.size = 1 * 1024 * 1024
+
+    # when
+    result = await dummy_endpoint(file=mocked_file)
+
+    # then
+    assert result == "success"
+
+
+@pytest.mark.asyncio
+async def test_file_size_validator_exactly_max_size():
+    # given
+    mocked_file = Mock()
+    mocked_file.size = 2 * 1024 * 1024
+
+    # when
+    result = await dummy_endpoint(file=mocked_file)
+
+    # then
+    assert result == "success"
+
+
+@pytest.mark.asyncio
+async def test_file_size_validator_too_large():
+    # given
+    mocked_file = Mock()
+    mocked_file.size = int(2.1 * 1024 * 1024)
+
+    # when
+    with pytest.raises(HTTPException) as exc_info:
+        await dummy_endpoint(file=mocked_file)
+
+    # then
+    assert exc_info.value.status_code == status.HTTP_413_CONTENT_TOO_LARGE
+    assert exc_info.value.detail == "file size is bigger than 2MB"
+
+
+@pytest.mark.asyncio
+async def test_file_size_validator_zero_or_none_size():
+    # given
+    mocked_file = Mock()
+    mocked_file.size = 0
+
+    mock_file_none = Mock()
+    mock_file_none.size = None
+
+    # when
+    result_zero = await dummy_endpoint(file=mocked_file)
+    result_none = await dummy_endpoint(file=mock_file_none)
+
+    # then
+    assert result_none == "success"
+    assert result_zero == "success"
+
+
+@pytest.mark.asyncio
+async def test_file_size_validator_missing_size_attribute():
+    # given
+    mocked_file = Mock(spec=[])
+
+    # when
+    result = await dummy_endpoint(file=mocked_file)
+
+    assert result == "success"

fastapi_file_validator-0.0.0/PKG-INFO

@@ -1,14 +0,0 @@
-Metadata-Version: 2.4
-Name: fastapi-file-validator
-Version: 0.0.0
-Summary: A lightweight, flexible file extension validator and MIME type checker for fastapi
-Author-email: Seungkyu-Han <trust1204@gmail.com>
-License: MIT
-Project-URL: Homepage, https://github.com/Seungkyu-Han/fastapi-file-validator
-Project-URL: Bug Tracker, https://github.com/Seungkyu-Han/fastapi-file-validator
-Project-URL: Documentation, https://github.com/Seungkyu-Han/fastapi-file-validator
-Project-URL: Source, https://github.com/Seungkyu-Han/fastapi-file-validator
-Keywords: validator
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: fastapi>=0.110.1

fastapi_file_validator-0.0.0/fastapi_file_validator.egg-info/PKG-INFO

@@ -1,14 +0,0 @@
-Metadata-Version: 2.4
-Name: fastapi-file-validator
-Version: 0.0.0
-Summary: A lightweight, flexible file extension validator and MIME type checker for fastapi
-Author-email: Seungkyu-Han <trust1204@gmail.com>
-License: MIT
-Project-URL: Homepage, https://github.com/Seungkyu-Han/fastapi-file-validator
-Project-URL: Bug Tracker, https://github.com/Seungkyu-Han/fastapi-file-validator
-Project-URL: Documentation, https://github.com/Seungkyu-Han/fastapi-file-validator
-Project-URL: Source, https://github.com/Seungkyu-Han/fastapi-file-validator
-Keywords: validator
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: fastapi>=0.110.1

fastapi_file_validator-0.0.0/file_validator/file_extension_validator.py

@@ -1,42 +0,0 @@
-import os
-
-from fastapi import UploadFile, HTTPException, status
-from functools import wraps
-
-
-def file_extension_validator(file_arg_name: str, file_extensions: set[str]):
-    def decorator(func):
-        @wraps(func)
-        async def wrapper(*args, **kwargs):
-            if file_arg_name in kwargs:
-
-                file_arg = kwargs.get(file_arg_name)
-
-                if not isinstance(file_arg, UploadFile):
-                    return await func(*args, **kwargs)
-
-                file: UploadFile = file_arg
-
-                filename: str | None = file.filename
-
-                if not filename:
-                    raise HTTPException(
-                        status_code=status.HTTP_400_BAD_REQUEST,
-                        detail=f"filename is empty",
-                    )
-
-                _, ext = os.path.splitext(filename)
-
-                file_extension = ext[1:].lower()
-
-                if file_extension not in file_extensions:
-                    raise HTTPException(
-                        status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
-                        detail=f"{file_extension} type is unavailable",
-                    )
-
-            return await func(*args, **kwargs)
-
-        return wrapper
-
-    return decorator

fastapi_file_validator-0.0.0/file_validator/file_size_validator.py

@@ -1,34 +0,0 @@
-from fastapi import UploadFile, HTTPException, status
-from functools import wraps
-
-
-def file_size_validator(file_arg_name: str, max_size_mb: int):
-    max_size_bytes = max_size_mb * 1024 * 1024
-
-    def decorator(func):
-        @wraps(func)
-        async def wrapper(*args, **kwargs):
-            if file_arg_name in kwargs:
-                file_arg = kwargs.get(file_arg_name)
-
-                if not isinstance(file_arg, UploadFile):
-                    return await func(*args, **kwargs)
-
-                file: UploadFile = file_arg
-
-                file_size: int | None = file.size
-
-                if not file_size:
-                    return await func(*args, **kwargs)
-
-                if file_size > max_size_bytes:
-                    raise HTTPException(
-                        status_code=status.HTTP_413_CONTENT_TOO_LARGE,
-                        detail=f"file size is bigger than {max_size_mb}MB",
-                    )
-
-            return await func(*args, **kwargs)
-
-        return wrapper
-
-    return decorator