# SmoothGlue Django File Uploader
A Django app providing secure, pluggable uploads to S3, MinIO, or local storage with validation, checksums, and post-processing. Built for regulated and edge environments from the ground up.
## Overview
`smoothglue_file_uploader` simplifies the process of handling file uploads in a Django project. The core problem it solves is abstracting the storage backend, allowing developers to switch between local development, staging, and production environments without changing application code. You can configure it once in `settings.py` and have your file uploads seamlessly route to the correct storage solution.
### Key Features
* **Multiple Storage Backends:** Natively supports Local Filesystem, Amazon S3, and MinIO.
* **Easy Configuration:** A single settings dictionary to control all storage options.
* **On-the-fly Validation:** Allows custom configurations to validate files prior to them being uploaded.
* **Ease of Access:** Easily upload, download, delete or duplicate files in any supported files stores.
## Installation
### Prerequisites
* Python 3.12+
* Django 4.2+
* Django REST Framework 3.14+
### Install App From PyPI Package (Official Use)
1. Before installing the package, make sure that there is a virtual environment set up inside of the Django project you want to install the app into.
2. Use pip and the following command inside the Django project:
```python
pip install smoothglue_file_uploader
```
3. Update the `settings.py` file inside that Django project to point to the new app name:
```python
INSTALLED_APPS = [
"smoothglue_file_uploader",
...,
]
```
4. Update the `urls.py` file inside that Django project to point to the new app name: :
```python
urlpatterns = [
path("", include("smoothglue_file_uploader.urls")),
...,
]
```
5. Run the development server to confirm the project continues to work.
## Examples
### Usage Examples
#### Download
```python
storage_provider, _ = get_storage_provider()
doc = Document.objects.get(id=instance.id)
data = storage_provider.download_document(doc.path)
```
#### Upload
```python
storage_provider, _ = get_storage_provider()
path = "foo/bar"
storage_provider.upload_document(path, file_obj)
```
#### Delete
```python
storage_provider, _ = get_storage_provider()
doc = Document.objects.get(id=instance.id)
storage_provider.delete_document(doc.path)
```
#### Duplicate
```python
storage_provider, _ = get_storage_provider()
old_doc = Document.objects.get(id=instance.id)
new_uuid = str(uuid.uuid4())
new_path = f"path/{new_uuid}"
duplicate_success = storage_provider.duplicate_document(old_doc.path, new_path)
```
### API Examples
| URL Path | HTTP Method | Description |
| -------- | ------- | ------- |
| `/` | `GET` | Lists documents. A `reference_id` (UUID) must be provided as a query parameter to retrieve all files associated with that ID. |
| `/` | `POST` | Uploads a new file. The request must be a multipart form containing a `file` and a `reference_id`. |
| `/<uuid:file_id>/` | `GET` | Downloads the content of the specified file as a file attachment. |
| `/<uuid:file_id>/` | `PATCH` | Updates the metadata (e.g., name, category) of the specified file. |
| `/<uuid:file_id>/` | `DELETE` | Deletes the specified file from the backend storage and the database. |
### Settings Example
``` python
UPLOAD_STORAGE_PROVIDER_CONFIG = {
"minio": {
"PROVIDER_CLASS": "smoothglue.file_uploader.storage_providers.minio.MinioProvider",
"PROVIDER_CONFIG": {
"ACCESS_KEY": os.getenv("ACCESS_KEY"),
"HOST": os.getenv("HOST"),
"PORT": int(os.getenv("MINIO_PORT")),
"SECRET_KEY": os.getenv("SECRET_KEY"),
"SECURE": True if os.getenv("MINIO_PROTOCOL") == "https" else False,
"BUCKET_NAME": os.getenv("BUCKET_NAME"),
"REGION": os.getenv("REGION"),
},
},
"s3-sts-web-id": {
"PROVIDER_CLASS": "smoothglue.file_uploader.storage_providers.s3.STSWebIdentityS3Provider",
"PROVIDER_CONFIG": {
"ROLE_ARN": os.getenv("ROLE_ARN", None),
"WEB_IDENTITY_TOKEN_FILE": os.getenv("WEB_IDENTITY_TOKEN_FILE", None),
"BUCKET_NAME": os.getenv("BUCKET_NAME", None),
},
},
"local": {
"PROVIDER_CLASS": "smoothglue.file_uploader.storage_providers.local.LocalFileSystemProvider",
"PROVIDER_CONFIG": {},
},
}
SELECTED_STORAGE_PROVIDER = os.getenv("DEFAULT_STORAGE_PROVIDER")
UPLOAD_STORAGE_PROVIDER_CONFIG["default"] = UPLOAD_STORAGE_PROVIDER_CONFIG[
SELECTED_STORAGE_PROVIDER
]
```
## Settings Overview
```python
# This setting defines the configs for the stores of smoothglue.file_uploader.storage_providers.base.StorageProvider
# which provides an interface for interacting with some storage providers. Each storage provider may come with its own
# required settings in the PROVIDER_CONFIG.
# "default" is what all files will be uploaded to without specifying a different key
UPLOAD_STORAGE_PROVIDER_CONFIG = {
"default": {
"PROVIDER_CLASS": "smoothglue.file_uploader.storage_providers.s3.BaseS3StorageProvider",
"PROVIDER_CONFIG": {...}
},
...}
# Required keys for smoothglue.file_uploader.storage_providers.s3.BaseS3StorageProvider
"BUCKET_NAME" = "..." # S3 bucket to store uploaded files in
# Required keys for smoothglue.file_uploader.storage_providers.s3.STSS3Provider
"ROLE_ARN" = "..." # IAM role for the credentials used to access S3
"BUCKET_NAME" = "..." # S3 bucket to store uploaded files in
# Required keys for smoothglue.file_uploader.storage_providers.s3.STSWebIdentityS3Provider
"ROLE_ARN" = "..." # IAM role for the credentials used to access S3
"WEB_IDENTITY_TOKEN_FILE" = "/path/to/identity/token.file"
"BUCKET_NAME" = "..." # S3 bucket to store uploaded files in
# Required keys for smoothglue.file_uploader.storage_providers.minio.MinioProvider
"ACCESS_KEY" = "..." # Access key for minio "user"
"HOST" = "minio.example.com" # Hostname or ip address of minio server
"PORT" = "1234" # (Optional) port minio service listens on if different from default
"SECRET_KEY" = "..." # Secret key for minio "user"
"SECURE" = True # True if Minio uses SSL, false otherwise
"BUCKET_NAME" = "..." # Minio bucket to store uploaded files in
# A dictionary of file extensions to post-processor classes. These post-processor classes are ran after a file has been
# successfully uploaded to the configured storage provider
UPLOAD_POST_PROCESSORS = {
# Will be applied to EVERY file uploaded
"*": "smoothglue.file_uploader.post_processor.DefaultUploadProcessor",
# Will be applied to all files uploaded that end in `.txt`
"txt": "some.other.post.processing.class"
}
# A dictionary of file extensions to file validator classes. These file validator classes are ran before a file is
# uploaded and may raise a validation error (resulting in 400 response).
UPLOAD_VALIDATORS = {
# Will be applied to EVERY file uploaded
"*": "smoothglue.file_uploader.validators.DefaultValidator",
# Will be applied to all files uploaded that end in `.txt`
"txt": "some.other.validation.class",
}
```
**Local File System Storage Provider**
Used for running a simple upload to the file system. Defaults go to the Django MEDIA_ROOT configuration, otherwise you can specify the location using `UPLOAD_PATH` in the config.
```
UPLOAD_STORAGE_PROVIDER_CONFIG = {
"default": {
"PROVIDER_CLASS": "smoothglue.file_uploader.storage_providers.local.LocalFileSystemProvider",
"PROVIDER_CONFIG": {"UPLOAD_PATH": "/tmp/uploaded_files"}
},
...
}
```
**Optional File Checksum validation**
```
# calculate sha256 file checksum and inserts it to the db. May cause performance issue for large file uploads
CALCULATE_CHECKSUM: bool = True
# Enforce checksum validation if an existing file with the same checksum exist in the document table.
UPLOAD_VALIDATORS={
"*": "smoothglue.file_uploader.validators.DuplicateFileValidator"
}
```
## License
This project is licensed under a Proprietary License. See the [LICENSE](./LICENSE) file for more details.
Raw data
{
"_id": null,
"home_page": "https://braingu.com/solutions/smoothglue/",
"name": "smoothglue_file_uploader",
"maintainer": "BrainGu",
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "smoothglue@braingu.com",
"keywords": "Interoperability, API Integration, Edge Computing, Application Framework, Data-Driven Development, Django, File Upload",
"author": "SmoothGlue",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ca/32/2324839c4ab025765d570bef10ebedc466f75fffc455b4636f31f63ffa67/smoothglue_file_uploader-1.0.1.tar.gz",
"platform": null,
"description": "# SmoothGlue Django File Uploader\n\nA Django app providing secure, pluggable uploads to S3, MinIO, or local storage with validation, checksums, and post-processing. Built for regulated and edge environments from the ground up.\n\n## Overview\n\n`smoothglue_file_uploader` simplifies the process of handling file uploads in a Django project. The core problem it solves is abstracting the storage backend, allowing developers to switch between local development, staging, and production environments without changing application code. You can configure it once in `settings.py` and have your file uploads seamlessly route to the correct storage solution.\n\n### Key Features\n\n* **Multiple Storage Backends:** Natively supports Local Filesystem, Amazon S3, and MinIO.\n* **Easy Configuration:** A single settings dictionary to control all storage options.\n* **On-the-fly Validation:** Allows custom configurations to validate files prior to them being uploaded.\n* **Ease of Access:** Easily upload, download, delete or duplicate files in any supported files stores.\n\n## Installation\n\n### Prerequisites\n\n* Python 3.12+\n* Django 4.2+\n* Django REST Framework 3.14+\n\n### Install App From PyPI Package (Official Use)\n\n1. Before installing the package, make sure that there is a virtual environment set up inside of the Django project you want to install the app into.\n\n2. Use pip and the following command inside the Django project:\n ```python\n pip install smoothglue_file_uploader\n ```\n\n3. Update the `settings.py` file inside that Django project to point to the new app name:\n\n ```python\n INSTALLED_APPS = [\n \"smoothglue_file_uploader\",\n ...,\n ]\n ```\n\n\n4. Update the `urls.py` file inside that Django project to point to the new app name: :\n\n ```python\n urlpatterns = [\n path(\"\", include(\"smoothglue_file_uploader.urls\")),\n ...,\n ]\n ```\n\n5. Run the development server to confirm the project continues to work.\n\n## Examples\n\n### Usage Examples\n\n#### Download\n```python\n storage_provider, _ = get_storage_provider()\n doc = Document.objects.get(id=instance.id)\n\n data = storage_provider.download_document(doc.path)\n```\n\n#### Upload\n```python\n storage_provider, _ = get_storage_provider()\n path = \"foo/bar\"\n storage_provider.upload_document(path, file_obj)\n```\n\n#### Delete\n```python\n storage_provider, _ = get_storage_provider()\n doc = Document.objects.get(id=instance.id)\n\n storage_provider.delete_document(doc.path)\n```\n\n#### Duplicate\n```python\n storage_provider, _ = get_storage_provider()\n old_doc = Document.objects.get(id=instance.id)\n new_uuid = str(uuid.uuid4())\n new_path = f\"path/{new_uuid}\"\n\n duplicate_success = storage_provider.duplicate_document(old_doc.path, new_path)\n```\n\n### API Examples\n\n| URL Path | HTTP Method | Description |\n| -------- | ------- | ------- |\n| `/` | `GET` | Lists documents. A `reference_id` (UUID) must be provided as a query parameter to retrieve all files associated with that ID. |\n| `/` | `POST` | Uploads a new file. The request must be a multipart form containing a `file` and a `reference_id`. |\n| `/<uuid:file_id>/` | `GET` | Downloads the content of the specified file as a file attachment. |\n| `/<uuid:file_id>/` | `PATCH` | Updates the metadata (e.g., name, category) of the specified file. |\n| `/<uuid:file_id>/` | `DELETE` | Deletes the specified file from the backend storage and the database. |\n\n\n### Settings Example\n\n``` python\nUPLOAD_STORAGE_PROVIDER_CONFIG = {\n \"minio\": {\n \"PROVIDER_CLASS\": \"smoothglue.file_uploader.storage_providers.minio.MinioProvider\",\n \"PROVIDER_CONFIG\": {\n \"ACCESS_KEY\": os.getenv(\"ACCESS_KEY\"),\n \"HOST\": os.getenv(\"HOST\"),\n \"PORT\": int(os.getenv(\"MINIO_PORT\")),\n \"SECRET_KEY\": os.getenv(\"SECRET_KEY\"),\n \"SECURE\": True if os.getenv(\"MINIO_PROTOCOL\") == \"https\" else False,\n \"BUCKET_NAME\": os.getenv(\"BUCKET_NAME\"),\n \"REGION\": os.getenv(\"REGION\"),\n },\n },\n \"s3-sts-web-id\": {\n \"PROVIDER_CLASS\": \"smoothglue.file_uploader.storage_providers.s3.STSWebIdentityS3Provider\",\n \"PROVIDER_CONFIG\": {\n \"ROLE_ARN\": os.getenv(\"ROLE_ARN\", None),\n \"WEB_IDENTITY_TOKEN_FILE\": os.getenv(\"WEB_IDENTITY_TOKEN_FILE\", None),\n \"BUCKET_NAME\": os.getenv(\"BUCKET_NAME\", None),\n },\n },\n \"local\": {\n \"PROVIDER_CLASS\": \"smoothglue.file_uploader.storage_providers.local.LocalFileSystemProvider\",\n \"PROVIDER_CONFIG\": {},\n },\n}\n\nSELECTED_STORAGE_PROVIDER = os.getenv(\"DEFAULT_STORAGE_PROVIDER\")\n\nUPLOAD_STORAGE_PROVIDER_CONFIG[\"default\"] = UPLOAD_STORAGE_PROVIDER_CONFIG[\n SELECTED_STORAGE_PROVIDER\n]\n```\n\n## Settings Overview\n```python\n# This setting defines the configs for the stores of smoothglue.file_uploader.storage_providers.base.StorageProvider\n# which provides an interface for interacting with some storage providers. Each storage provider may come with its own\n# required settings in the PROVIDER_CONFIG.\n\n# \"default\" is what all files will be uploaded to without specifying a different key\nUPLOAD_STORAGE_PROVIDER_CONFIG = {\n \"default\": {\n \"PROVIDER_CLASS\": \"smoothglue.file_uploader.storage_providers.s3.BaseS3StorageProvider\",\n \"PROVIDER_CONFIG\": {...}\n},\n...}\n\n# Required keys for smoothglue.file_uploader.storage_providers.s3.BaseS3StorageProvider\n\"BUCKET_NAME\" = \"...\" # S3 bucket to store uploaded files in\n\n# Required keys for smoothglue.file_uploader.storage_providers.s3.STSS3Provider\n\"ROLE_ARN\" = \"...\" # IAM role for the credentials used to access S3\n\"BUCKET_NAME\" = \"...\" # S3 bucket to store uploaded files in\n\n# Required keys for smoothglue.file_uploader.storage_providers.s3.STSWebIdentityS3Provider\n\"ROLE_ARN\" = \"...\" # IAM role for the credentials used to access S3\n\"WEB_IDENTITY_TOKEN_FILE\" = \"/path/to/identity/token.file\"\n\"BUCKET_NAME\" = \"...\" # S3 bucket to store uploaded files in\n\n# Required keys for smoothglue.file_uploader.storage_providers.minio.MinioProvider\n\"ACCESS_KEY\" = \"...\" # Access key for minio \"user\"\n\"HOST\" = \"minio.example.com\" # Hostname or ip address of minio server\n\"PORT\" = \"1234\" # (Optional) port minio service listens on if different from default\n\"SECRET_KEY\" = \"...\" # Secret key for minio \"user\"\n\"SECURE\" = True # True if Minio uses SSL, false otherwise\n\"BUCKET_NAME\" = \"...\" # Minio bucket to store uploaded files in\n\n# A dictionary of file extensions to post-processor classes. These post-processor classes are ran after a file has been\n# successfully uploaded to the configured storage provider\nUPLOAD_POST_PROCESSORS = {\n # Will be applied to EVERY file uploaded\n \"*\": \"smoothglue.file_uploader.post_processor.DefaultUploadProcessor\",\n # Will be applied to all files uploaded that end in `.txt`\n \"txt\": \"some.other.post.processing.class\"\n}\n\n# A dictionary of file extensions to file validator classes. These file validator classes are ran before a file is\n# uploaded and may raise a validation error (resulting in 400 response).\nUPLOAD_VALIDATORS = {\n # Will be applied to EVERY file uploaded\n \"*\": \"smoothglue.file_uploader.validators.DefaultValidator\",\n # Will be applied to all files uploaded that end in `.txt`\n \"txt\": \"some.other.validation.class\",\n}\n```\n\n**Local File System Storage Provider**\n\nUsed for running a simple upload to the file system. Defaults go to the Django MEDIA_ROOT configuration, otherwise you can specify the location using `UPLOAD_PATH` in the config.\n\n```\nUPLOAD_STORAGE_PROVIDER_CONFIG = {\n \"default\": {\n \"PROVIDER_CLASS\": \"smoothglue.file_uploader.storage_providers.local.LocalFileSystemProvider\",\n \"PROVIDER_CONFIG\": {\"UPLOAD_PATH\": \"/tmp/uploaded_files\"}\n},\n...\n}\n```\n\n**Optional File Checksum validation**\n\n```\n# calculate sha256 file checksum and inserts it to the db. May cause performance issue for large file uploads\nCALCULATE_CHECKSUM: bool = True\n\n# Enforce checksum validation if an existing file with the same checksum exist in the document table.\n\nUPLOAD_VALIDATORS={\n \"*\": \"smoothglue.file_uploader.validators.DuplicateFileValidator\"\n}\n```\n\n## License\n\nThis project is licensed under a Proprietary License. See the [LICENSE](./LICENSE) file for more details.\n",
"bugtrack_url": null,
"license": "Proprietary",
"summary": "SmoothGlue GuC2 File Uploader: a Django app providing secure, pluggable uploads to S3, MinIO, or local storage with validation, checksums, and post-processing. Built for regulated and edge environments from the ground up.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://braingu.com/solutions/smoothglue/"
},
"split_keywords": [
"interoperability",
" api integration",
" edge computing",
" application framework",
" data-driven development",
" django",
" file upload"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93efedc670075c7d5da7e0986c8ae5f4574aa108517354c6b29ae22bda98e7b9",
"md5": "ea4e8e6174846f8421385e873420a5ee",
"sha256": "51f56bf9f091020d760de24f31e900749583a49ed2b3bc2c1e8c9eb0f9406ff7"
},
"downloads": -1,
"filename": "smoothglue_file_uploader-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea4e8e6174846f8421385e873420a5ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 26193,
"upload_time": "2025-08-18T15:43:00",
"upload_time_iso_8601": "2025-08-18T15:43:00.354902Z",
"url": "https://files.pythonhosted.org/packages/93/ef/edc670075c7d5da7e0986c8ae5f4574aa108517354c6b29ae22bda98e7b9/smoothglue_file_uploader-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ca322324839c4ab025765d570bef10ebedc466f75fffc455b4636f31f63ffa67",
"md5": "002606d2bf6a90275b225d524dd33427",
"sha256": "a1894a3629c122ac20b737e2ad21b23258cc41f1115464db2f11d85dadaecf5e"
},
"downloads": -1,
"filename": "smoothglue_file_uploader-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "002606d2bf6a90275b225d524dd33427",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 28699,
"upload_time": "2025-08-18T15:43:01",
"upload_time_iso_8601": "2025-08-18T15:43:01.515990Z",
"url": "https://files.pythonhosted.org/packages/ca/32/2324839c4ab025765d570bef10ebedc466f75fffc455b4636f31f63ffa67/smoothglue_file_uploader-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 15:43:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "smoothglue_file_uploader"
}
JSON