| Name | django-filehub JSON |
| Version |
3.0
JSON |
| download |
| home_page | None |
| Summary | FileHub is a Django-based file management app that simplifies file handling within your Django projects. It supports file uploads, storage, and retrieval, making it easy to integrate robust file management features into your applications. |
| upload_time | 2025-02-02 12:39:30 |
| maintainer | None |
| docs_url | None |
| author | Suresh Chand |
| requires_python | None |
| license | BSD |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center" id="title">Django FileHub</h1>
<p align="center"><img src="https://socialify.git.ci/scthakuri/django-filehub/image?font=Inter&forks=1&issues=1&language=1&name=1&owner=1&pattern=Circuit%20Board&pulls=1&stargazers=1&theme=Light" alt="project-image"></p>
FileHub is a Django-based file management app that simplifies file handling within your Django projects. It supports file uploads, storage, and retrieval, making it easy to integrate robust file management features into your applications.
## Features
- **File Uploads**: Seamlessly handle file uploads in your Django project.
- **File Storage**: Organize and store files with customizable configurations.
- **File Retrieval**: Efficiently access and manage uploaded files.
- **File Categories**: Automatically categorize files based on type.
- **Sorting Options**: Flexible sorting by name, size, or date, with ascending/descending order.
- **Custom Fields**: Use `ImagePickerField` and `ImagePickerWidget` for advanced image selection in forms.
## Installation
1. Install django-filehub using [pip](https://pip.pypa.io/en/stable/) (or any other way to install python package) from [PyPI](https://pypi.org/).
```bash
pip install django-filehub
```
2. Add `filehub` to INSTALLED_APPS in `settings.py` for your project:
```python
INSTALLED_APPS = (
...
'filehub',
...
)
```
3. Add `filehub.urls` to `urls.py` for your project:
```python
urlpatterns = patterns('',
...
path('admin/', include('filehub.urls')),
...
)
```
4. Make migrations to add necessary database tables
```bash
python manage.py migrate
```
## Configuration
### 1. **Login URL for File Access Control**
To secure file access, define a login URL that redirects unauthorized users to the login page:
```python
FILEHUB_LOGIN_URL = "/login/"
```
- Description:
- This URL will be used as a fallback for unauthorized access to media files.
- Users attempting to access restricted files will be redirected to this URL.
### 2. **Media File Settings**
Django requires `MEDIA_URL` and `MEDIA_ROOT` to manage uploaded files. Add the following settings:
```python
MEDIA_URL = "media/"
MEDIA_ROOT = "path/to/media"
```
- MEDIA_URL:
- Specifies the base public URL to serve media files.
- Example: If `MEDIA_URL = "media/"`, uploaded files will be accessible at http://yourdomain.com/media/.
- MEDIA_ROOT:
- Defines the absolute path to the directory where media files are stored.
- Replace `"path/to/media"` with the full path to your desired directory.
### 3. **Upload Directory Configuration**
Define the directory where files will be uploaded within the `MEDIA_ROOT` directory. By default, this is set to `uploads`, but you can change it as needed.
```python
DIRECTORY = "uploads"
```
- Description:
- This setting determines the subdirectory inside the `MEDIA_ROOT` where uploaded files will be stored.
- The default value is `"uploads"`, meaning that files will be uploaded to `MEDIA_ROOT/uploads/`.
- You can change this value to any directory name you prefer (e.g., `"files"`, `"documents"`, etc.).
- Ensure the specified directory exists within the `MEDIA_ROOT` or Django will create it when files are uploaded.
### 4. **File Type Categories**
Organize files into specific categories based on their extensions. Add the following dictionary to define supported file types:
```python
FILE_TYPE_CATEGORIES = {
'images': ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'tiff', 'webp'],
'videos': ['mp4', 'webm', 'ogg', 'avi', 'mkv', 'mov', 'wmv', '3gp', 'mpeg', 'mpg4'],
'musics': ['mp3', 'wav', 'flac', 'aac', 'wma', 'm4a'],
'archives': ['zip', 'rar', 'tar', 'gz']
}
```
- Description:
- This dictionary categorizes files by type and extension for better organization.
- Each key represents a category (e.g., `images`, `videos`), and the value is a list of associated file extensions.
### 5. **Theme Color Configuration**
You can customize the theme color of the Filehub file manager interface by setting the `FILEHUB_THEME_COLOR`.
```python
FILEHUB_THEME_COLOR = "#3498db"
```
- Description:
- This setting allows you to change the theme color of the Filehub file manager interface.
- The color is specified using a Hex color code. You can set it to any valid Hex color (e.g., `#3498db` for blue, `#e74c3c` for red).
- This provides a way to customize the visual appearance of the file manager to better match your site's theme.
## Custom Fields
Django Filehub also supports the following custom field and widget for advanced image selection:
### 1. **ImagePickerField**
`ImagePickerField` is a custom Django model field used to store image file paths as text. This field makes it easier to handle image selections by allowing you to store the image path in your model without the need for manually handling file uploads.
#### Example Usage:
```python
from filehub.fields import ImagePickerField
class ExampleModel(models.Model):
image = ImagePickerField()
```
- Description:
- The ImagePickerField stores the file path of the selected image in your model as a text field.
- It does not directly handle the image upload process; rather, it works with an image picker interface that allows the user to choose images.
- This is particularly useful when you want to allow users to select images from a pre-defined set or directory rather than uploading new images each time.
### 2. **ImagePickerWidget**
`ImagePickerWidget` is a custom Django form widget designed to allow users to select images via a file picker interface in forms. It is typically used alongside the `ImagePickerField` in Django forms to enhance the image selection experience.
```python
from filehub.widgets import ImagePickerWidget
from django import forms
class ExampleForm(forms.Form):
image = forms.CharField(widget=ImagePickerWidget())
```
- Description:
- The ImagePickerWidget is a custom form widget that renders a file picker interface in the form, allowing users to select an image.
- It works by rendering a text field where users can either enter an image path or use the widget’s file picker to select an image.
- This widget is designed to work with the ImagePickerField model field, which stores the image file path.
## Additional Notes
### Serving Media Files via AWS S3 Buckets
To serve media files via AWS S3 in your Django project, you'll need to configure `django-storages` to handle the interaction with S3.
#### 1. Install django-storages
First, you need to install `django-storages` to manage media files with AWS S3:
```bash
pip install "django-storages[s3]"
```
#### 2. Configure AWS S3 in Django Settings
In your `settings.py`, add the following configurations:
```bash
# AWS S3 Configuration for Serving Media Files
AWS_ACCESS_KEY_ID = 'your-access-key-id'
AWS_SECRET_ACCESS_KEY = 'your-secret-access-key'
AWS_STORAGE_BUCKET_NAME = 'your-bucket-name'
AWS_S3_REGION_NAME = 'your-region' # e.g., 'us-east-1'
AWS_S3_CUSTOM_DOMAIN = f"{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com" # Customize if using CloudFront
AWS_S3_FILE_OVERWRITE = False # Prevent overwriting files with the same name
AWS_DEFAULT_ACL = 'public-read' # Files will be publicly accessible
# Optionally, if you want to use a custom URL for your media files:
AWS_S3_URL = f'https://{AWS_S3_CUSTOM_DOMAIN}/' # Adjust if using CloudFront
```
Make sure to replace placeholders like `'your-access-key-id'`, `'your-secret-access-key'`, and `'your-bucket-name'` with your actual AWS credentials and settings.
#### 3. Set MEDIA_URL (Required) and STATIC_URL (Optional)
Configure the URLs for both static and media files:
```bash
# URL for serving Media files
MEDIA_URL = f'https://{AWS_S3_CUSTOM_DOMAIN}/'
# URL for serving Static files (Optional)
STATIC_URL = f'https://{AWS_S3_STATIC_CUSTOM_DOMAIN}/static/' # Optional
```
If you do not wish to use a custom `STATIC_URL` and prefer using the default Django static setup, you can skip setting `STATIC_URL`. This is optional.
#### 4. Run collectstatic for Static Files
To upload static files to your S3 bucket, run the following command:
```bash
python manage.py collectstatic
```
This command will gather all static files and push them to your S3 bucket under the static/ folder.
For more configuration settings, [check AWS config here](https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html)
### Serving Media Files in Development
During development, you can serve media files by adding the following to your `urls.py`:
```bash
from django.conf import settings
from django.conf.urls.static import static
if settings.DEBUG:
urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
```
### Serving Media Files in Production
In production, use a web server like **Nginx** or **Apache** to serve media files efficiently. Ensure the `MEDIA_ROOT` directory is properly configured.
## Contributing
Contributions are welcome! If you'd like to report issues, suggest new features, or contribute to the development, please submit a pull request or open an issue.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-filehub",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Suresh Chand",
"author_email": "scthakuri12a@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f7/8f/0409c657f1b14e9b99ac1adc1094fee3b6f0bd65ccc67d5021e10cffbc97/django_filehub-3.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\" id=\"title\">Django FileHub</h1>\n\n<p align=\"center\"><img src=\"https://socialify.git.ci/scthakuri/django-filehub/image?font=Inter&forks=1&issues=1&language=1&name=1&owner=1&pattern=Circuit%20Board&pulls=1&stargazers=1&theme=Light\" alt=\"project-image\"></p>\n\nFileHub is a Django-based file management app that simplifies file handling within your Django projects. It supports file uploads, storage, and retrieval, making it easy to integrate robust file management features into your applications.\n\n## Features\n\n- **File Uploads**: Seamlessly handle file uploads in your Django project.\n- **File Storage**: Organize and store files with customizable configurations.\n- **File Retrieval**: Efficiently access and manage uploaded files.\n- **File Categories**: Automatically categorize files based on type.\n- **Sorting Options**: Flexible sorting by name, size, or date, with ascending/descending order.\n- **Custom Fields**: Use `ImagePickerField` and `ImagePickerWidget` for advanced image selection in forms.\n\n## Installation\n\n1. Install django-filehub using [pip](https://pip.pypa.io/en/stable/) (or any other way to install python package) from [PyPI](https://pypi.org/).\n\n```bash\npip install django-filehub\n```\n\n2. Add `filehub` to INSTALLED_APPS in `settings.py` for your project:\n\n```python\nINSTALLED_APPS = (\n ...\n 'filehub',\n ...\n)\n```\n\n3. Add `filehub.urls` to `urls.py` for your project:\n\n```python\nurlpatterns = patterns('',\n ...\n path('admin/', include('filehub.urls')),\n ...\n)\n```\n\n4. Make migrations to add necessary database tables\n\n```bash\npython manage.py migrate\n```\n\n## Configuration\n\n### 1. **Login URL for File Access Control**\n\nTo secure file access, define a login URL that redirects unauthorized users to the login page:\n\n```python\nFILEHUB_LOGIN_URL = \"/login/\"\n```\n\n- Description:\n - This URL will be used as a fallback for unauthorized access to media files.\n - Users attempting to access restricted files will be redirected to this URL.\n\n### 2. **Media File Settings**\n\nDjango requires `MEDIA_URL` and `MEDIA_ROOT` to manage uploaded files. Add the following settings:\n\n```python\nMEDIA_URL = \"media/\"\nMEDIA_ROOT = \"path/to/media\"\n```\n\n- MEDIA_URL:\n - Specifies the base public URL to serve media files.\n - Example: If `MEDIA_URL = \"media/\"`, uploaded files will be accessible at http://yourdomain.com/media/.\n\n- MEDIA_ROOT:\n - Defines the absolute path to the directory where media files are stored.\n - Replace `\"path/to/media\"` with the full path to your desired directory.\n\n\n### 3. **Upload Directory Configuration**\n\nDefine the directory where files will be uploaded within the `MEDIA_ROOT` directory. By default, this is set to `uploads`, but you can change it as needed.\n\n```python\nDIRECTORY = \"uploads\"\n```\n\n- Description:\n - This setting determines the subdirectory inside the `MEDIA_ROOT` where uploaded files will be stored.\n - The default value is `\"uploads\"`, meaning that files will be uploaded to `MEDIA_ROOT/uploads/`.\n - You can change this value to any directory name you prefer (e.g., `\"files\"`, `\"documents\"`, etc.).\n - Ensure the specified directory exists within the `MEDIA_ROOT` or Django will create it when files are uploaded.\n\n### 4. **File Type Categories**\n\nOrganize files into specific categories based on their extensions. Add the following dictionary to define supported file types:\n\n```python\nFILE_TYPE_CATEGORIES = {\n 'images': ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'tiff', 'webp'],\n 'videos': ['mp4', 'webm', 'ogg', 'avi', 'mkv', 'mov', 'wmv', '3gp', 'mpeg', 'mpg4'],\n 'musics': ['mp3', 'wav', 'flac', 'aac', 'wma', 'm4a'],\n 'archives': ['zip', 'rar', 'tar', 'gz']\n}\n```\n\n- Description:\n - This dictionary categorizes files by type and extension for better organization.\n - Each key represents a category (e.g., `images`, `videos`), and the value is a list of associated file extensions.\n\n### 5. **Theme Color Configuration**\n\nYou can customize the theme color of the Filehub file manager interface by setting the `FILEHUB_THEME_COLOR`.\n\n```python\nFILEHUB_THEME_COLOR = \"#3498db\"\n```\n\n- Description:\n - This setting allows you to change the theme color of the Filehub file manager interface.\n - The color is specified using a Hex color code. You can set it to any valid Hex color (e.g., `#3498db` for blue, `#e74c3c` for red).\n - This provides a way to customize the visual appearance of the file manager to better match your site's theme.\n\n## Custom Fields\n\nDjango Filehub also supports the following custom field and widget for advanced image selection:\n\n### 1. **ImagePickerField**\n\n`ImagePickerField` is a custom Django model field used to store image file paths as text. This field makes it easier to handle image selections by allowing you to store the image path in your model without the need for manually handling file uploads.\n\n#### Example Usage:\n\n```python\nfrom filehub.fields import ImagePickerField\n\nclass ExampleModel(models.Model):\n image = ImagePickerField()\n```\n\n- Description:\n - The ImagePickerField stores the file path of the selected image in your model as a text field.\n - It does not directly handle the image upload process; rather, it works with an image picker interface that allows the user to choose images.\n - This is particularly useful when you want to allow users to select images from a pre-defined set or directory rather than uploading new images each time.\n\n### 2. **ImagePickerWidget**\n\n`ImagePickerWidget` is a custom Django form widget designed to allow users to select images via a file picker interface in forms. It is typically used alongside the `ImagePickerField` in Django forms to enhance the image selection experience.\n\n```python\nfrom filehub.widgets import ImagePickerWidget\nfrom django import forms\n\nclass ExampleForm(forms.Form):\n image = forms.CharField(widget=ImagePickerWidget())\n```\n\n- Description:\n - The ImagePickerWidget is a custom form widget that renders a file picker interface in the form, allowing users to select an image.\n - It works by rendering a text field where users can either enter an image path or use the widget\u2019s file picker to select an image.\n - This widget is designed to work with the ImagePickerField model field, which stores the image file path.\n\n\n## Additional Notes\n\n### Serving Media Files via AWS S3 Buckets\n\nTo serve media files via AWS S3 in your Django project, you'll need to configure `django-storages` to handle the interaction with S3.\n\n#### 1. Install django-storages\n\nFirst, you need to install `django-storages` to manage media files with AWS S3:\n\n```bash\npip install \"django-storages[s3]\"\n```\n\n#### 2. Configure AWS S3 in Django Settings\n\nIn your `settings.py`, add the following configurations:\n\n```bash\n# AWS S3 Configuration for Serving Media Files\nAWS_ACCESS_KEY_ID = 'your-access-key-id'\nAWS_SECRET_ACCESS_KEY = 'your-secret-access-key'\nAWS_STORAGE_BUCKET_NAME = 'your-bucket-name'\nAWS_S3_REGION_NAME = 'your-region' # e.g., 'us-east-1'\nAWS_S3_CUSTOM_DOMAIN = f\"{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com\" # Customize if using CloudFront\nAWS_S3_FILE_OVERWRITE = False # Prevent overwriting files with the same name\nAWS_DEFAULT_ACL = 'public-read' # Files will be publicly accessible\n\n# Optionally, if you want to use a custom URL for your media files:\nAWS_S3_URL = f'https://{AWS_S3_CUSTOM_DOMAIN}/' # Adjust if using CloudFront\n```\n\nMake sure to replace placeholders like `'your-access-key-id'`, `'your-secret-access-key'`, and `'your-bucket-name'` with your actual AWS credentials and settings.\n\n#### 3. Set MEDIA_URL (Required) and STATIC_URL (Optional)\n\nConfigure the URLs for both static and media files:\n\n```bash\n# URL for serving Media files\nMEDIA_URL = f'https://{AWS_S3_CUSTOM_DOMAIN}/'\n\n# URL for serving Static files (Optional)\nSTATIC_URL = f'https://{AWS_S3_STATIC_CUSTOM_DOMAIN}/static/' # Optional\n```\n\nIf you do not wish to use a custom `STATIC_URL` and prefer using the default Django static setup, you can skip setting `STATIC_URL`. This is optional.\n\n#### 4. Run collectstatic for Static Files\n\nTo upload static files to your S3 bucket, run the following command:\n\n```bash\npython manage.py collectstatic\n```\n\nThis command will gather all static files and push them to your S3 bucket under the static/ folder.\n\nFor more configuration settings, [check AWS config here](https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html)\n\n### Serving Media Files in Development\n\nDuring development, you can serve media files by adding the following to your `urls.py`:\n\n```bash\nfrom django.conf import settings\nfrom django.conf.urls.static import static\n\nif settings.DEBUG:\n urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)\n```\n\n### Serving Media Files in Production\n\nIn production, use a web server like **Nginx** or **Apache** to serve media files efficiently. Ensure the `MEDIA_ROOT` directory is properly configured.\n\n## Contributing\nContributions are welcome! If you'd like to report issues, suggest new features, or contribute to the development, please submit a pull request or open an issue.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "FileHub is a Django-based file management app that simplifies file handling within your Django projects. It supports file uploads, storage, and retrieval, making it easy to integrate robust file management features into your applications.",
"version": "3.0",
"project_urls": {
"Bug Reports": "https://github.com/scthakuri/django-filehub/issues",
"Source": "https://github.com/scthakuri/django-filehub"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dfef1bf2e1b281df7c406cf564e78f3a4a91dac19c7a659d8fcaaaaec1866336",
"md5": "2d71280b2f6906eea77e9d4ea850d6e6",
"sha256": "c57879065fe79b6544b67630199048133ca3b3929de5129fdc58cbc8cf15f44e"
},
"downloads": -1,
"filename": "django_filehub-3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d71280b2f6906eea77e9d4ea850d6e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 67855,
"upload_time": "2025-02-02T12:39:25",
"upload_time_iso_8601": "2025-02-02T12:39:25.960881Z",
"url": "https://files.pythonhosted.org/packages/df/ef/1bf2e1b281df7c406cf564e78f3a4a91dac19c7a659d8fcaaaaec1866336/django_filehub-3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f78f0409c657f1b14e9b99ac1adc1094fee3b6f0bd65ccc67d5021e10cffbc97",
"md5": "1b513fdb619a0aad98ed30928a7b11d6",
"sha256": "90d0fd41180399aa60bad4baeea73e0c7692e7e53d4c40bd61fec275e4cf2452"
},
"downloads": -1,
"filename": "django_filehub-3.0.tar.gz",
"has_sig": false,
"md5_digest": "1b513fdb619a0aad98ed30928a7b11d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 53219,
"upload_time": "2025-02-02T12:39:30",
"upload_time_iso_8601": "2025-02-02T12:39:30.854115Z",
"url": "https://files.pythonhosted.org/packages/f7/8f/0409c657f1b14e9b99ac1adc1094fee3b6f0bd65ccc67d5021e10cffbc97/django_filehub-3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-02 12:39:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scthakuri",
"github_project": "django-filehub",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-filehub"
}
