image-upload 0.1.0__tar.gz

image_upload-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahil Sheoran
+
+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.

image_upload-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: image-upload
+Version: 0.1.0
+Summary: Image Upload Package for FastAPI
+Author-email: Sahil Sheoran <sahilsheoran24@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: fastapi>=0.138.2
+Requires-Dist: pydantic>=2.13.4
+Dynamic: license-file
+
+# image-upload
+
+A lightweight FastAPI package for saving uploaded files and generating absolute URLs for stored images using Pydantic.
+
+## Features
+
+* Simple file upload handling
+* Automatically stores files inside an `uploads/` directory
+* Returns the saved file path
+* Easily generate absolute URLs with Pydantic
+* Asynchronous file saving using `aiofiles`
+* File size and MIME type validation
+
+---
+
+## Requirements
+
+- Python 3.12+
+- FastAPI
+- Pydantic v2
+- aiofiles
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install image-upload
+```
+
+---
+
+## Supported File Types
+
+By default the package accepts:
+
+- JPEG (`image/jpeg`)
+- PNG (`image/png`)
+- GIF (`image/gif`)
+- PDF (`application/pdf`)
+- Plain Text (`text/plain`)
+
+Maximum upload size is **50 MB**.
+
+---
+
+## Saving an Uploaded File
+
+Import `get_path` and pass an `UploadFile`.
+
+```python
+from image_upload import get_path
+
+data.picture = await get_path(data.picture)
+```
+
+or
+
+```python
+data["picture"] = await get_path(data.pop("picture"))
+```
+
+The function returns the relative storage path.
+
+Example output:
+
+```text
+uploads/0c6d8a69-9c84-47d4-81f6-d15d11fcbf88.png
+```
+
+---
+
+## FastAPI Example
+
+```python
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from image_upload import get_path
+
+router = APIRouter()
+
+@router.post("/")
+async def create(
+    data: UserCreate = Depends(UserCreate.as_form),
+    db: AsyncSession = Depends(get_db),
+):
+    data.picture = await get_path(data.picture)
+
+    return await user(db, data.model_dump())
+```
+
+---
+
+## Save Inside a Custom Folder
+
+You can optionally provide a folder name.
+
+```python
+path = await get_path(file, folder="users")
+```
+
+---
+
+## Building Absolute URLs
+
+`AbsoluteUrl` automatically prepends the application's base URL using the Pydantic validation context.
+
+```python
+from pydantic import BaseModel
+from image_upload import AbsoluteUrl
+
+class UserOut(BaseModel):
+    name: str
+    picture: AbsoluteUrl
+```
+
+When validating:
+
+```python
+user = UserOut.model_validate(
+    data,
+    context={
+        "base_url": "https://example.com/"
+    }
+)
+```
+
+## Note: Can also use "base_url": request.base_url
+
+```python
+from fastapi import Request
+
+@router.get("/")
+async def get_user(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> UserOut:
+    users = await list_user(
+        db
+    )
+
+    return UserOut.model_validate(
+        users,
+        context={"base_url": request.base_url},
+    )
+
+```
+
+Result:
+
+```json
+{
+    "name": "John",
+    "picture": "https://example.com/uploads/avatar.png"
+}
+```
+
+---
+
+## API
+
+### `get_path(file, folder=None)`
+
+Stores the uploaded file and returns its storage path.
+
+**Parameters**
+
+| Parameter | Type        | Description             |
+|-----------|-------------|-------------------------|
+| file      | UploadFile  | Uploaded file           |
+| folder    | str | None  | Optional folder prefix  |
+
+**Returns**
+
+```python
+str
+```
+
+Example:
+
+```python
+path = await get_path(upload_file)
+```
+
+---
+
+## Security
+
+The package performs basic validation:
+
+- Allowed MIME type validation
+- Maximum file size validation (50 MB)
+- UUID-based file names to avoid collisions
+- Asynchronous streaming to reduce memory usage
+
+---
+
+## Dependencies
+
+- FastAPI
+- Pydantic v2
+- aiofiles
+
+---
+
+## License
+
+MIT License

image_upload-0.1.0/README.md

@@ -0,0 +1,211 @@
+# image-upload
+
+A lightweight FastAPI package for saving uploaded files and generating absolute URLs for stored images using Pydantic.
+
+## Features
+
+* Simple file upload handling
+* Automatically stores files inside an `uploads/` directory
+* Returns the saved file path
+* Easily generate absolute URLs with Pydantic
+* Asynchronous file saving using `aiofiles`
+* File size and MIME type validation
+
+---
+
+## Requirements
+
+- Python 3.12+
+- FastAPI
+- Pydantic v2
+- aiofiles
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install image-upload
+```
+
+---
+
+## Supported File Types
+
+By default the package accepts:
+
+- JPEG (`image/jpeg`)
+- PNG (`image/png`)
+- GIF (`image/gif`)
+- PDF (`application/pdf`)
+- Plain Text (`text/plain`)
+
+Maximum upload size is **50 MB**.
+
+---
+
+## Saving an Uploaded File
+
+Import `get_path` and pass an `UploadFile`.
+
+```python
+from image_upload import get_path
+
+data.picture = await get_path(data.picture)
+```
+
+or
+
+```python
+data["picture"] = await get_path(data.pop("picture"))
+```
+
+The function returns the relative storage path.
+
+Example output:
+
+```text
+uploads/0c6d8a69-9c84-47d4-81f6-d15d11fcbf88.png
+```
+
+---
+
+## FastAPI Example
+
+```python
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from image_upload import get_path
+
+router = APIRouter()
+
+@router.post("/")
+async def create(
+    data: UserCreate = Depends(UserCreate.as_form),
+    db: AsyncSession = Depends(get_db),
+):
+    data.picture = await get_path(data.picture)
+
+    return await user(db, data.model_dump())
+```
+
+---
+
+## Save Inside a Custom Folder
+
+You can optionally provide a folder name.
+
+```python
+path = await get_path(file, folder="users")
+```
+
+---
+
+## Building Absolute URLs
+
+`AbsoluteUrl` automatically prepends the application's base URL using the Pydantic validation context.
+
+```python
+from pydantic import BaseModel
+from image_upload import AbsoluteUrl
+
+class UserOut(BaseModel):
+    name: str
+    picture: AbsoluteUrl
+```
+
+When validating:
+
+```python
+user = UserOut.model_validate(
+    data,
+    context={
+        "base_url": "https://example.com/"
+    }
+)
+```
+
+## Note: Can also use "base_url": request.base_url
+
+```python
+from fastapi import Request
+
+@router.get("/")
+async def get_user(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> UserOut:
+    users = await list_user(
+        db
+    )
+
+    return UserOut.model_validate(
+        users,
+        context={"base_url": request.base_url},
+    )
+
+```
+
+Result:
+
+```json
+{
+    "name": "John",
+    "picture": "https://example.com/uploads/avatar.png"
+}
+```
+
+---
+
+## API
+
+### `get_path(file, folder=None)`
+
+Stores the uploaded file and returns its storage path.
+
+**Parameters**
+
+| Parameter | Type        | Description             |
+|-----------|-------------|-------------------------|
+| file      | UploadFile  | Uploaded file           |
+| folder    | str | None  | Optional folder prefix  |
+
+**Returns**
+
+```python
+str
+```
+
+Example:
+
+```python
+path = await get_path(upload_file)
+```
+
+---
+
+## Security
+
+The package performs basic validation:
+
+- Allowed MIME type validation
+- Maximum file size validation (50 MB)
+- UUID-based file names to avoid collisions
+- Asynchronous streaming to reduce memory usage
+
+---
+
+## Dependencies
+
+- FastAPI
+- Pydantic v2
+- aiofiles
+
+---
+
+## License
+
+MIT License

image_upload-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "image-upload"
+version = "0.1.0"
+description = "Image Upload Package for FastAPI"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+
+authors = [
+    {name = "Sahil Sheoran", email = "sahilsheoran24@gmail.com"}
+]
+
+dependencies = [
+    "aiofiles>=25.1.0",
+    "fastapi>=0.138.2",
+    "pydantic>=2.13.4",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+license-files = ["LICENSE.txt"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "build>=1.5.0",
+    "twine>=6.2.0",
+]

image_upload-0.1.0/setup.cfg

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

image_upload-0.1.0/src/image_upload/__init__.py

@@ -0,0 +1,8 @@
+from .save_file import process_upload, get_path
+from .add_base_url import AbsoluteUrl
+
+__all__ = [
+    "process_upload",
+    "get_path",
+    "AbsoluteUrl",
+]

image_upload-0.1.0/src/image_upload/add_base_url.py

@@ -0,0 +1,12 @@
+from pydantic.functional_validators import BeforeValidator
+from pydantic import ValidationInfo
+from typing_extensions import Annotated
+from typing import Optional
+
+def append_base_url(v: Optional[str], info: ValidationInfo) -> Optional[str]:
+    if v is not None and info.context:
+        base_url = info.context.get("base_url", "")
+        return f"{base_url}{v}"
+    return v
+
+AbsoluteUrl = Annotated[Optional[str], BeforeValidator(append_base_url)]

image_upload-0.1.0/src/image_upload/save_file.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+from pydantic import BaseModel
+from fastapi import FastAPI, UploadFile, HTTPException
+
+import aiofiles
+import uuid
+import hashlib
+
+class UploadConfig:
+    UPLOAD_DIR = Path("uploads")
+    MAX_FILE_SIZE = 50 * 1024 * 1024 # 50 MB
+    ALLOWED_TYPES = {
+        "image/jpeg", "image/png", "image/gif",
+        "application/pdf", "text/plain"
+    }
+    CHUNK_SIZE = 1024 * 1024 # 1 MB
+
+config = UploadConfig()
+config.UPLOAD_DIR.mkdir(exist_ok=True)
+
+
+class UploadResult(BaseModel):
+    id: str
+    filename: str
+    storage_path: Path
+    size: int
+    content_type: str
+
+
+async def process_upload(file: UploadFile, folder: str | None = None) -> UploadResult:
+    
+    if file.content_type not in config.ALLOWED_TYPES:
+        raise HTTPException(
+            status_code=400,
+            detail=f"File type not allowed: {file.content_type}"
+        )
+    
+    file_id = str(uuid.uuid4())
+    if folder:
+        folder_path = config.UPLOAD_DIR / Path(folder)
+        folder_path.mkdir(parents=True, exist_ok=True)
+        extension = Path(file.filename).suffix
+        storage_path = config.UPLOAD_DIR / folder / f"{file_id}{extension}"
+    else:
+        extension = Path(file.filename).suffix
+        storage_path = config.UPLOAD_DIR / f"{file_id}{extension}"
+
+    hasher = hashlib.shake_256()
+    total_size = 0
+
+    async with aiofiles.open(storage_path, "wb") as out:
+        while chunk := await file.read(config.CHUNK_SIZE):
+            total_size +=len(chunk)
+
+            if total_size > config.MAX_FILE_SIZE:
+                storage_path.unlink(missing_ok=True)
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"File exceeds maximum size of {config.MAX_FILE_SIZE // (1024*1024)} MB"
+                )
+            
+            await out.write(chunk)
+            hasher.update(chunk)
+
+    return UploadResult(
+        id=file_id,
+        filename=file.filename,
+        storage_path=storage_path,
+        size=total_size,
+        content_type=file.content_type
+    )
+
+async def get_path(file: UploadFile, folder: str | None = None) -> str:
+    upload = await process_upload(file, folder)
+
+    return str(upload.storage_path)

image_upload-0.1.0/src/image_upload.egg-info/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: image-upload
+Version: 0.1.0
+Summary: Image Upload Package for FastAPI
+Author-email: Sahil Sheoran <sahilsheoran24@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: fastapi>=0.138.2
+Requires-Dist: pydantic>=2.13.4
+Dynamic: license-file
+
+# image-upload
+
+A lightweight FastAPI package for saving uploaded files and generating absolute URLs for stored images using Pydantic.
+
+## Features
+
+* Simple file upload handling
+* Automatically stores files inside an `uploads/` directory
+* Returns the saved file path
+* Easily generate absolute URLs with Pydantic
+* Asynchronous file saving using `aiofiles`
+* File size and MIME type validation
+
+---
+
+## Requirements
+
+- Python 3.12+
+- FastAPI
+- Pydantic v2
+- aiofiles
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install image-upload
+```
+
+---
+
+## Supported File Types
+
+By default the package accepts:
+
+- JPEG (`image/jpeg`)
+- PNG (`image/png`)
+- GIF (`image/gif`)
+- PDF (`application/pdf`)
+- Plain Text (`text/plain`)
+
+Maximum upload size is **50 MB**.
+
+---
+
+## Saving an Uploaded File
+
+Import `get_path` and pass an `UploadFile`.
+
+```python
+from image_upload import get_path
+
+data.picture = await get_path(data.picture)
+```
+
+or
+
+```python
+data["picture"] = await get_path(data.pop("picture"))
+```
+
+The function returns the relative storage path.
+
+Example output:
+
+```text
+uploads/0c6d8a69-9c84-47d4-81f6-d15d11fcbf88.png
+```
+
+---
+
+## FastAPI Example
+
+```python
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from image_upload import get_path
+
+router = APIRouter()
+
+@router.post("/")
+async def create(
+    data: UserCreate = Depends(UserCreate.as_form),
+    db: AsyncSession = Depends(get_db),
+):
+    data.picture = await get_path(data.picture)
+
+    return await user(db, data.model_dump())
+```
+
+---
+
+## Save Inside a Custom Folder
+
+You can optionally provide a folder name.
+
+```python
+path = await get_path(file, folder="users")
+```
+
+---
+
+## Building Absolute URLs
+
+`AbsoluteUrl` automatically prepends the application's base URL using the Pydantic validation context.
+
+```python
+from pydantic import BaseModel
+from image_upload import AbsoluteUrl
+
+class UserOut(BaseModel):
+    name: str
+    picture: AbsoluteUrl
+```
+
+When validating:
+
+```python
+user = UserOut.model_validate(
+    data,
+    context={
+        "base_url": "https://example.com/"
+    }
+)
+```
+
+## Note: Can also use "base_url": request.base_url
+
+```python
+from fastapi import Request
+
+@router.get("/")
+async def get_user(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> UserOut:
+    users = await list_user(
+        db
+    )
+
+    return UserOut.model_validate(
+        users,
+        context={"base_url": request.base_url},
+    )
+
+```
+
+Result:
+
+```json
+{
+    "name": "John",
+    "picture": "https://example.com/uploads/avatar.png"
+}
+```
+
+---
+
+## API
+
+### `get_path(file, folder=None)`
+
+Stores the uploaded file and returns its storage path.
+
+**Parameters**
+
+| Parameter | Type        | Description             |
+|-----------|-------------|-------------------------|
+| file      | UploadFile  | Uploaded file           |
+| folder    | str | None  | Optional folder prefix  |
+
+**Returns**
+
+```python
+str
+```
+
+Example:
+
+```python
+path = await get_path(upload_file)
+```
+
+---
+
+## Security
+
+The package performs basic validation:
+
+- Allowed MIME type validation
+- Maximum file size validation (50 MB)
+- UUID-based file names to avoid collisions
+- Asynchronous streaming to reduce memory usage
+
+---
+
+## Dependencies
+
+- FastAPI
+- Pydantic v2
+- aiofiles
+
+---
+
+## License
+
+MIT License

image_upload-0.1.0/src/image_upload.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE.txt
+README.md
+pyproject.toml
+src/image_upload/__init__.py
+src/image_upload/add_base_url.py
+src/image_upload/save_file.py
+src/image_upload.egg-info/PKG-INFO
+src/image_upload.egg-info/SOURCES.txt
+src/image_upload.egg-info/dependency_links.txt
+src/image_upload.egg-info/requires.txt
+src/image_upload.egg-info/top_level.txt

image_upload-0.1.0/src/image_upload.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

image_upload-0.1.0/src/image_upload.egg-info/requires.txt

@@ -0,0 +1,3 @@
+aiofiles>=25.1.0
+fastapi>=0.138.2
+pydantic>=2.13.4

image_upload-0.1.0/src/image_upload.egg-info/top_level.txt

@@ -0,0 +1 @@
+image_upload