django-admin-filemanager 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. django_admin_filemanager-1.0.0/LICENSE +21 -0
  2. django_admin_filemanager-1.0.0/MANIFEST.in +6 -0
  3. django_admin_filemanager-1.0.0/PKG-INFO +169 -0
  4. django_admin_filemanager-1.0.0/README.md +132 -0
  5. django_admin_filemanager-1.0.0/django_admin_filemanager.egg-info/PKG-INFO +169 -0
  6. django_admin_filemanager-1.0.0/django_admin_filemanager.egg-info/SOURCES.txt +39 -0
  7. django_admin_filemanager-1.0.0/django_admin_filemanager.egg-info/dependency_links.txt +1 -0
  8. django_admin_filemanager-1.0.0/django_admin_filemanager.egg-info/requires.txt +1 -0
  9. django_admin_filemanager-1.0.0/django_admin_filemanager.egg-info/top_level.txt +1 -0
  10. django_admin_filemanager-1.0.0/filemanager/__init__.py +0 -0
  11. django_admin_filemanager-1.0.0/filemanager/admin.py +254 -0
  12. django_admin_filemanager-1.0.0/filemanager/apps.py +8 -0
  13. django_admin_filemanager-1.0.0/filemanager/locale/en/LC_MESSAGES/django.mo +0 -0
  14. django_admin_filemanager-1.0.0/filemanager/locale/en/LC_MESSAGES/django.po +288 -0
  15. django_admin_filemanager-1.0.0/filemanager/locale/ru/LC_MESSAGES/django.mo +0 -0
  16. django_admin_filemanager-1.0.0/filemanager/locale/ru/LC_MESSAGES/django.po +289 -0
  17. django_admin_filemanager-1.0.0/filemanager/migrations/0001_initial.py +32 -0
  18. django_admin_filemanager-1.0.0/filemanager/migrations/__init__.py +0 -0
  19. django_admin_filemanager-1.0.0/filemanager/models.py +13 -0
  20. django_admin_filemanager-1.0.0/filemanager/static/filemanager/browse.js +85 -0
  21. django_admin_filemanager-1.0.0/filemanager/static/filemanager/html_textarea.js +100 -0
  22. django_admin_filemanager-1.0.0/filemanager/storage.py +220 -0
  23. django_admin_filemanager-1.0.0/filemanager/templates/admin/filemanager/base.html +44 -0
  24. django_admin_filemanager-1.0.0/filemanager/templates/admin/filemanager/browse.html +110 -0
  25. django_admin_filemanager-1.0.0/filemanager/templates/admin/filemanager/delete.html +35 -0
  26. django_admin_filemanager-1.0.0/filemanager/templates/admin/filemanager/path.html +1 -0
  27. django_admin_filemanager-1.0.0/filemanager/templates/admin/filemanager/rename.html +25 -0
  28. django_admin_filemanager-1.0.0/filemanager/templates/admin/filemanager/usage.html +11 -0
  29. django_admin_filemanager-1.0.0/filemanager/templates/admin/filemanager/usage_list.html +16 -0
  30. django_admin_filemanager-1.0.0/filemanager/templates/filemanager/widgets/html_textarea.html +3 -0
  31. django_admin_filemanager-1.0.0/filemanager/tests/__init__.py +9 -0
  32. django_admin_filemanager-1.0.0/filemanager/tests/settings.py +52 -0
  33. django_admin_filemanager-1.0.0/filemanager/tests/test_admin.py +227 -0
  34. django_admin_filemanager-1.0.0/filemanager/tests/test_storage.py +115 -0
  35. django_admin_filemanager-1.0.0/filemanager/tests/test_widgets.py +30 -0
  36. django_admin_filemanager-1.0.0/filemanager/tests/urls.py +6 -0
  37. django_admin_filemanager-1.0.0/filemanager/usage.py +77 -0
  38. django_admin_filemanager-1.0.0/filemanager/widgets.py +27 -0
  39. django_admin_filemanager-1.0.0/pyproject.toml +50 -0
  40. django_admin_filemanager-1.0.0/setup.cfg +4 -0
  41. django_admin_filemanager-1.0.0/tox.ini +40 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Andrey Novikov
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,6 @@
1
+ include LICENSE
2
+ include README.md
3
+ include MANIFEST.in
4
+ include tox.ini
5
+ recursive-include filemanager *.py *.html *.js *.css *.po *.mo
6
+ global-exclude *.py[cod] __pycache__
@@ -0,0 +1,169 @@
1
+ Metadata-Version: 2.4
2
+ Name: django-admin-filemanager
3
+ Version: 1.0.0
4
+ Summary: File manager in the Django admin for the files that HTML text links to
5
+ Author-email: Andrey Novikov <novikov@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/andreynovikov/django-admin-filemanager
8
+ Project-URL: Repository, https://github.com/andreynovikov/django-admin-filemanager.git
9
+ Project-URL: Issues, https://github.com/andreynovikov/django-admin-filemanager/issues
10
+ Project-URL: Releases, https://github.com/andreynovikov/django-admin-filemanager/releases
11
+ Keywords: django,admin,file manager,file browser,media,upload,widget
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Environment :: Web Environment
14
+ Classifier: Framework :: Django
15
+ Classifier: Framework :: Django :: 5.2
16
+ Classifier: Framework :: Django :: 6.0
17
+ Classifier: Framework :: Django :: 6.1
18
+ Classifier: Intended Audience :: Developers
19
+ Classifier: Natural Language :: English
20
+ Classifier: Natural Language :: Russian
21
+ Classifier: Operating System :: OS Independent
22
+ Classifier: Programming Language :: Python
23
+ Classifier: Programming Language :: Python :: 3
24
+ Classifier: Programming Language :: Python :: 3 :: Only
25
+ Classifier: Programming Language :: Python :: 3.10
26
+ Classifier: Programming Language :: Python :: 3.11
27
+ Classifier: Programming Language :: Python :: 3.12
28
+ Classifier: Programming Language :: Python :: 3.13
29
+ Classifier: Programming Language :: Python :: 3.14
30
+ Classifier: Programming Language :: Python :: 3.15
31
+ Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
32
+ Requires-Python: >=3.10
33
+ Description-Content-Type: text/markdown
34
+ License-File: LICENSE
35
+ Requires-Dist: Django>=5.2
36
+ Dynamic: license-file
37
+
38
+ # File manager in the Django admin
39
+
40
+ [![Test status](https://github.com/andreynovikov/django-admin-filemanager/actions/workflows/test.yaml/badge.svg)](https://github.com/andreynovikov/django-admin-filemanager/actions/workflows/test.yaml)
41
+ [![GitHub release](https://img.shields.io/github/release/andreynovikov/django-admin-filemanager.svg)](https://github.com/andreynovikov/django-admin-filemanager/releases/latest)
42
+ [![PyPI release](https://img.shields.io/pypi/v/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
43
+ [![Python version](https://img.shields.io/pypi/pyversions/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
44
+ [![Django version](https://img.shields.io/pypi/frameworkversions/django/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
45
+ [![GitHub issues](https://img.shields.io/github/issues/andreynovikov/django-admin-filemanager.svg)](https://github.com/andreynovikov/django-admin-filemanager/issues)
46
+ [![GitHub license](https://img.shields.io/github/license/andreynovikov/django-admin-filemanager.svg)](LICENSE)
47
+
48
+ A file browser in the Django admin for the files that pages link to by URL: images, videos and documents in HTML text. It works like a file system. Folders nest freely, files keep the names they are uploaded with, and replacing a file keeps its URL. Files have no versions.
49
+
50
+ ## Features
51
+
52
+ - **Browsing.** A folder at a time, with its folders and files, sizes and modification times. Hidden names (with a leading dot) and names that aren't UTF-8 are not shown. Files can be sorted by name, size or modification time, and the order stays while you move between folders.
53
+ - **Translations of labels.** Short labels such as "Delete" have the context `file manager`, so that the catalogs of apps installed earlier, which take precedence, don't replace them.
54
+ - **Uploading.** Several files at a time, by dropping them on the page or choosing them. A file whose name exists is replaced only after the browser asks. The new content is written beside the old file and renamed over it, so its URL never serves a partial file.
55
+ - **Folders.** Making, renaming, moving and deleting folders. Deleting a folder deletes everything in it, after a confirmation that says how many files it holds.
56
+ - **Renaming and moving** files and folders. The new path is typed from the root, and missing folders are made.
57
+ - **Where used.** Lists the records that link to a file or to the files of a folder. The rename and delete pages show it before anything changes. See [Where used](#where-used).
58
+ - **Protected folders.** Folders that hold the files of model fields (`FileField`, `ImageField`) can be browsed and linked from, but not changed.
59
+ - **HTML widget.** A text area for HTML fields that grows with its text, with an "Insert file" button that opens the browser in a popup. The chosen file goes into the text at the cursor: `<img>` for images, `<video controls>` for videos and `<a>` for other files.
60
+ - **Permissions:** the model permissions of `filemanager.File`:
61
+ - view: browse, copy URLs, see where a file is used;
62
+ - add: upload new files and make folders;
63
+ - change: replace, rename and move;
64
+ - delete: delete.
65
+ - **Translations:** English and Russian.
66
+
67
+ ## Requirements
68
+
69
+ - Python 3.10 or later.
70
+ - Django 5.2 or later; 5.2, 6.0 and 6.1 are tested.
71
+ - A `FileSystemStorage`. Another storage, such as S3, needs a store class in `storage.py`, see [Other storages](#other-storages).
72
+
73
+ ## Installation
74
+
75
+ 1. Install the package. It is named `django-admin-filemanager`, and its app is `filemanager`.
76
+
77
+ ```shell
78
+ pip install django-admin-filemanager
79
+ ```
80
+
81
+ 2. Add `'filemanager'` to `INSTALLED_APPS`. Its templates and scripts are found by the default template loaders and static file finders.
82
+ 3. Run `python manage.py migrate filemanager`. The model has no table, but the migration creates its permissions.
83
+ 4. Give the `HTMLTextarea` widget to the fields that hold HTML, see [The HTML widget](#the-html-widget).
84
+
85
+ The browser is at the changelist URL of `filemanager.File`, `admin:filemanager_file_changelist`.
86
+
87
+ ## The HTML widget
88
+
89
+ `filemanager.widgets.HTMLTextarea` is an admin text area for HTML. It grows with its text, also in collapsed fieldsets and in inline rows added later. A `max-height` in its style still applies, and the text area scrolls beyond it. Its "Insert file" button opens the browser in a popup.
90
+
91
+ ```python
92
+ from filemanager.widgets import HTMLTextarea
93
+
94
+ class PageAdminForm(forms.ModelForm):
95
+ class Meta:
96
+ widgets = {
97
+ 'content': HTMLTextarea(attrs={'rows': 10, 'style': 'width: 95%; max-height: 500px'}),
98
+ }
99
+ ```
100
+
101
+ `admin_site` names the admin site whose browser the button opens, `'admin'` by default. The button is left out where that site's URLs aren't installed. The widget doesn't know the user, so users without file permissions see the button too. The browser then refuses them.
102
+
103
+ ## Settings
104
+
105
+ | Setting | Default | |
106
+ |---|---|---|
107
+ | `FILEMANAGER_STORAGE` | `'default'` | The alias in `STORAGES` of the storage whose files are managed. |
108
+ | `FILEMANAGER_PROTECTED` | `[]` | Paths from the root, such as `'products'`, that are read-only together with everything below them. List the `upload_to` folders of your file fields. |
109
+ | `FILEMANAGER_USAGE_EXCLUDE` | `[]` | App labels (`'django_celery_results'`) or models (`'shop.Order'`) that "where used" doesn't search. |
110
+
111
+ ## Where used
112
+
113
+ The text fields (`TextField`) of every model registered in the admin site are searched for `/` followed by the path, as stored and as it appears in a URL (`a b.jpg` and `a%20b.jpg`). That finds `/media/images/a.jpg`, `https://example.com/media/images/a.jpg` and aliases that keep the end of the path, such as `/images/a.jpg`. A short path at the root can also match a longer one: `/a.jpg` matches `/images/a.jpg`. Each search scans the tables, which is fine for pages opened one at a time. Exclude big tables that hold no links.
114
+
115
+ Rename and move don't change the links. The rename page lists the records to fix.
116
+
117
+ ## Caching
118
+
119
+ Replacing a file keeps its URL, so the URL mustn't be cached for long. Serve the files with a short `max-age`, and with `ETag` or `Last-Modified` so that clients can revalidate. An image cache in front of the files, such as Next.js image optimization, keeps old copies for its own TTL.
120
+
121
+ ## Other storages
122
+
123
+ The views use a store returned by `storage.get_store()`, and `FileSystemStore` is the only one so far. A store for an object storage implements the same methods. Folders are key prefixes there, so renaming one means copying and deleting each object under it, and an empty folder needs a placeholder object. Its `save()` puts the object under its final key, which replaces it in one step.
124
+
125
+ ## Development
126
+
127
+ ### Tests
128
+
129
+ In a project that has the app installed:
130
+
131
+ ```shell
132
+ python manage.py test filemanager
133
+ ```
134
+
135
+ On all supported Python and Django versions, with [tox](https://tox.wiki/):
136
+
137
+ ```shell
138
+ tox
139
+ ```
140
+
141
+ Or once, without a project, on SQLite, in the repository's root:
142
+
143
+ ```shell
144
+ python -m django test filemanager --settings=filemanager.tests.settings
145
+ ```
146
+
147
+ ### Translations
148
+
149
+ The source strings are English, and `filemanager/locale/` holds the English and Russian catalogs. To update them after changing strings, run this in the `filemanager` directory (it needs GNU gettext):
150
+
151
+ ```shell
152
+ django-admin makemessages -l en -l ru
153
+ django-admin compilemessages
154
+ ```
155
+
156
+ ### Releases
157
+
158
+ Set the new version in `pyproject.toml`, commit, then tag the commit and push the tag:
159
+
160
+ ```shell
161
+ git tag v1.0.1
162
+ git push origin v1.0.1
163
+ ```
164
+
165
+ The `publish` workflow tests the tag, publishes it to TestPyPI and PyPI and creates a GitHub release with notes generated from the commits.
166
+
167
+ ## License
168
+
169
+ [MIT](LICENSE)
@@ -0,0 +1,132 @@
1
+ # File manager in the Django admin
2
+
3
+ [![Test status](https://github.com/andreynovikov/django-admin-filemanager/actions/workflows/test.yaml/badge.svg)](https://github.com/andreynovikov/django-admin-filemanager/actions/workflows/test.yaml)
4
+ [![GitHub release](https://img.shields.io/github/release/andreynovikov/django-admin-filemanager.svg)](https://github.com/andreynovikov/django-admin-filemanager/releases/latest)
5
+ [![PyPI release](https://img.shields.io/pypi/v/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
6
+ [![Python version](https://img.shields.io/pypi/pyversions/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
7
+ [![Django version](https://img.shields.io/pypi/frameworkversions/django/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
8
+ [![GitHub issues](https://img.shields.io/github/issues/andreynovikov/django-admin-filemanager.svg)](https://github.com/andreynovikov/django-admin-filemanager/issues)
9
+ [![GitHub license](https://img.shields.io/github/license/andreynovikov/django-admin-filemanager.svg)](LICENSE)
10
+
11
+ A file browser in the Django admin for the files that pages link to by URL: images, videos and documents in HTML text. It works like a file system. Folders nest freely, files keep the names they are uploaded with, and replacing a file keeps its URL. Files have no versions.
12
+
13
+ ## Features
14
+
15
+ - **Browsing.** A folder at a time, with its folders and files, sizes and modification times. Hidden names (with a leading dot) and names that aren't UTF-8 are not shown. Files can be sorted by name, size or modification time, and the order stays while you move between folders.
16
+ - **Translations of labels.** Short labels such as "Delete" have the context `file manager`, so that the catalogs of apps installed earlier, which take precedence, don't replace them.
17
+ - **Uploading.** Several files at a time, by dropping them on the page or choosing them. A file whose name exists is replaced only after the browser asks. The new content is written beside the old file and renamed over it, so its URL never serves a partial file.
18
+ - **Folders.** Making, renaming, moving and deleting folders. Deleting a folder deletes everything in it, after a confirmation that says how many files it holds.
19
+ - **Renaming and moving** files and folders. The new path is typed from the root, and missing folders are made.
20
+ - **Where used.** Lists the records that link to a file or to the files of a folder. The rename and delete pages show it before anything changes. See [Where used](#where-used).
21
+ - **Protected folders.** Folders that hold the files of model fields (`FileField`, `ImageField`) can be browsed and linked from, but not changed.
22
+ - **HTML widget.** A text area for HTML fields that grows with its text, with an "Insert file" button that opens the browser in a popup. The chosen file goes into the text at the cursor: `<img>` for images, `<video controls>` for videos and `<a>` for other files.
23
+ - **Permissions:** the model permissions of `filemanager.File`:
24
+ - view: browse, copy URLs, see where a file is used;
25
+ - add: upload new files and make folders;
26
+ - change: replace, rename and move;
27
+ - delete: delete.
28
+ - **Translations:** English and Russian.
29
+
30
+ ## Requirements
31
+
32
+ - Python 3.10 or later.
33
+ - Django 5.2 or later; 5.2, 6.0 and 6.1 are tested.
34
+ - A `FileSystemStorage`. Another storage, such as S3, needs a store class in `storage.py`, see [Other storages](#other-storages).
35
+
36
+ ## Installation
37
+
38
+ 1. Install the package. It is named `django-admin-filemanager`, and its app is `filemanager`.
39
+
40
+ ```shell
41
+ pip install django-admin-filemanager
42
+ ```
43
+
44
+ 2. Add `'filemanager'` to `INSTALLED_APPS`. Its templates and scripts are found by the default template loaders and static file finders.
45
+ 3. Run `python manage.py migrate filemanager`. The model has no table, but the migration creates its permissions.
46
+ 4. Give the `HTMLTextarea` widget to the fields that hold HTML, see [The HTML widget](#the-html-widget).
47
+
48
+ The browser is at the changelist URL of `filemanager.File`, `admin:filemanager_file_changelist`.
49
+
50
+ ## The HTML widget
51
+
52
+ `filemanager.widgets.HTMLTextarea` is an admin text area for HTML. It grows with its text, also in collapsed fieldsets and in inline rows added later. A `max-height` in its style still applies, and the text area scrolls beyond it. Its "Insert file" button opens the browser in a popup.
53
+
54
+ ```python
55
+ from filemanager.widgets import HTMLTextarea
56
+
57
+ class PageAdminForm(forms.ModelForm):
58
+ class Meta:
59
+ widgets = {
60
+ 'content': HTMLTextarea(attrs={'rows': 10, 'style': 'width: 95%; max-height: 500px'}),
61
+ }
62
+ ```
63
+
64
+ `admin_site` names the admin site whose browser the button opens, `'admin'` by default. The button is left out where that site's URLs aren't installed. The widget doesn't know the user, so users without file permissions see the button too. The browser then refuses them.
65
+
66
+ ## Settings
67
+
68
+ | Setting | Default | |
69
+ |---|---|---|
70
+ | `FILEMANAGER_STORAGE` | `'default'` | The alias in `STORAGES` of the storage whose files are managed. |
71
+ | `FILEMANAGER_PROTECTED` | `[]` | Paths from the root, such as `'products'`, that are read-only together with everything below them. List the `upload_to` folders of your file fields. |
72
+ | `FILEMANAGER_USAGE_EXCLUDE` | `[]` | App labels (`'django_celery_results'`) or models (`'shop.Order'`) that "where used" doesn't search. |
73
+
74
+ ## Where used
75
+
76
+ The text fields (`TextField`) of every model registered in the admin site are searched for `/` followed by the path, as stored and as it appears in a URL (`a b.jpg` and `a%20b.jpg`). That finds `/media/images/a.jpg`, `https://example.com/media/images/a.jpg` and aliases that keep the end of the path, such as `/images/a.jpg`. A short path at the root can also match a longer one: `/a.jpg` matches `/images/a.jpg`. Each search scans the tables, which is fine for pages opened one at a time. Exclude big tables that hold no links.
77
+
78
+ Rename and move don't change the links. The rename page lists the records to fix.
79
+
80
+ ## Caching
81
+
82
+ Replacing a file keeps its URL, so the URL mustn't be cached for long. Serve the files with a short `max-age`, and with `ETag` or `Last-Modified` so that clients can revalidate. An image cache in front of the files, such as Next.js image optimization, keeps old copies for its own TTL.
83
+
84
+ ## Other storages
85
+
86
+ The views use a store returned by `storage.get_store()`, and `FileSystemStore` is the only one so far. A store for an object storage implements the same methods. Folders are key prefixes there, so renaming one means copying and deleting each object under it, and an empty folder needs a placeholder object. Its `save()` puts the object under its final key, which replaces it in one step.
87
+
88
+ ## Development
89
+
90
+ ### Tests
91
+
92
+ In a project that has the app installed:
93
+
94
+ ```shell
95
+ python manage.py test filemanager
96
+ ```
97
+
98
+ On all supported Python and Django versions, with [tox](https://tox.wiki/):
99
+
100
+ ```shell
101
+ tox
102
+ ```
103
+
104
+ Or once, without a project, on SQLite, in the repository's root:
105
+
106
+ ```shell
107
+ python -m django test filemanager --settings=filemanager.tests.settings
108
+ ```
109
+
110
+ ### Translations
111
+
112
+ The source strings are English, and `filemanager/locale/` holds the English and Russian catalogs. To update them after changing strings, run this in the `filemanager` directory (it needs GNU gettext):
113
+
114
+ ```shell
115
+ django-admin makemessages -l en -l ru
116
+ django-admin compilemessages
117
+ ```
118
+
119
+ ### Releases
120
+
121
+ Set the new version in `pyproject.toml`, commit, then tag the commit and push the tag:
122
+
123
+ ```shell
124
+ git tag v1.0.1
125
+ git push origin v1.0.1
126
+ ```
127
+
128
+ The `publish` workflow tests the tag, publishes it to TestPyPI and PyPI and creates a GitHub release with notes generated from the commits.
129
+
130
+ ## License
131
+
132
+ [MIT](LICENSE)
@@ -0,0 +1,169 @@
1
+ Metadata-Version: 2.4
2
+ Name: django-admin-filemanager
3
+ Version: 1.0.0
4
+ Summary: File manager in the Django admin for the files that HTML text links to
5
+ Author-email: Andrey Novikov <novikov@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/andreynovikov/django-admin-filemanager
8
+ Project-URL: Repository, https://github.com/andreynovikov/django-admin-filemanager.git
9
+ Project-URL: Issues, https://github.com/andreynovikov/django-admin-filemanager/issues
10
+ Project-URL: Releases, https://github.com/andreynovikov/django-admin-filemanager/releases
11
+ Keywords: django,admin,file manager,file browser,media,upload,widget
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Environment :: Web Environment
14
+ Classifier: Framework :: Django
15
+ Classifier: Framework :: Django :: 5.2
16
+ Classifier: Framework :: Django :: 6.0
17
+ Classifier: Framework :: Django :: 6.1
18
+ Classifier: Intended Audience :: Developers
19
+ Classifier: Natural Language :: English
20
+ Classifier: Natural Language :: Russian
21
+ Classifier: Operating System :: OS Independent
22
+ Classifier: Programming Language :: Python
23
+ Classifier: Programming Language :: Python :: 3
24
+ Classifier: Programming Language :: Python :: 3 :: Only
25
+ Classifier: Programming Language :: Python :: 3.10
26
+ Classifier: Programming Language :: Python :: 3.11
27
+ Classifier: Programming Language :: Python :: 3.12
28
+ Classifier: Programming Language :: Python :: 3.13
29
+ Classifier: Programming Language :: Python :: 3.14
30
+ Classifier: Programming Language :: Python :: 3.15
31
+ Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
32
+ Requires-Python: >=3.10
33
+ Description-Content-Type: text/markdown
34
+ License-File: LICENSE
35
+ Requires-Dist: Django>=5.2
36
+ Dynamic: license-file
37
+
38
+ # File manager in the Django admin
39
+
40
+ [![Test status](https://github.com/andreynovikov/django-admin-filemanager/actions/workflows/test.yaml/badge.svg)](https://github.com/andreynovikov/django-admin-filemanager/actions/workflows/test.yaml)
41
+ [![GitHub release](https://img.shields.io/github/release/andreynovikov/django-admin-filemanager.svg)](https://github.com/andreynovikov/django-admin-filemanager/releases/latest)
42
+ [![PyPI release](https://img.shields.io/pypi/v/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
43
+ [![Python version](https://img.shields.io/pypi/pyversions/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
44
+ [![Django version](https://img.shields.io/pypi/frameworkversions/django/django-admin-filemanager.svg)](https://pypi.org/project/django-admin-filemanager/)
45
+ [![GitHub issues](https://img.shields.io/github/issues/andreynovikov/django-admin-filemanager.svg)](https://github.com/andreynovikov/django-admin-filemanager/issues)
46
+ [![GitHub license](https://img.shields.io/github/license/andreynovikov/django-admin-filemanager.svg)](LICENSE)
47
+
48
+ A file browser in the Django admin for the files that pages link to by URL: images, videos and documents in HTML text. It works like a file system. Folders nest freely, files keep the names they are uploaded with, and replacing a file keeps its URL. Files have no versions.
49
+
50
+ ## Features
51
+
52
+ - **Browsing.** A folder at a time, with its folders and files, sizes and modification times. Hidden names (with a leading dot) and names that aren't UTF-8 are not shown. Files can be sorted by name, size or modification time, and the order stays while you move between folders.
53
+ - **Translations of labels.** Short labels such as "Delete" have the context `file manager`, so that the catalogs of apps installed earlier, which take precedence, don't replace them.
54
+ - **Uploading.** Several files at a time, by dropping them on the page or choosing them. A file whose name exists is replaced only after the browser asks. The new content is written beside the old file and renamed over it, so its URL never serves a partial file.
55
+ - **Folders.** Making, renaming, moving and deleting folders. Deleting a folder deletes everything in it, after a confirmation that says how many files it holds.
56
+ - **Renaming and moving** files and folders. The new path is typed from the root, and missing folders are made.
57
+ - **Where used.** Lists the records that link to a file or to the files of a folder. The rename and delete pages show it before anything changes. See [Where used](#where-used).
58
+ - **Protected folders.** Folders that hold the files of model fields (`FileField`, `ImageField`) can be browsed and linked from, but not changed.
59
+ - **HTML widget.** A text area for HTML fields that grows with its text, with an "Insert file" button that opens the browser in a popup. The chosen file goes into the text at the cursor: `<img>` for images, `<video controls>` for videos and `<a>` for other files.
60
+ - **Permissions:** the model permissions of `filemanager.File`:
61
+ - view: browse, copy URLs, see where a file is used;
62
+ - add: upload new files and make folders;
63
+ - change: replace, rename and move;
64
+ - delete: delete.
65
+ - **Translations:** English and Russian.
66
+
67
+ ## Requirements
68
+
69
+ - Python 3.10 or later.
70
+ - Django 5.2 or later; 5.2, 6.0 and 6.1 are tested.
71
+ - A `FileSystemStorage`. Another storage, such as S3, needs a store class in `storage.py`, see [Other storages](#other-storages).
72
+
73
+ ## Installation
74
+
75
+ 1. Install the package. It is named `django-admin-filemanager`, and its app is `filemanager`.
76
+
77
+ ```shell
78
+ pip install django-admin-filemanager
79
+ ```
80
+
81
+ 2. Add `'filemanager'` to `INSTALLED_APPS`. Its templates and scripts are found by the default template loaders and static file finders.
82
+ 3. Run `python manage.py migrate filemanager`. The model has no table, but the migration creates its permissions.
83
+ 4. Give the `HTMLTextarea` widget to the fields that hold HTML, see [The HTML widget](#the-html-widget).
84
+
85
+ The browser is at the changelist URL of `filemanager.File`, `admin:filemanager_file_changelist`.
86
+
87
+ ## The HTML widget
88
+
89
+ `filemanager.widgets.HTMLTextarea` is an admin text area for HTML. It grows with its text, also in collapsed fieldsets and in inline rows added later. A `max-height` in its style still applies, and the text area scrolls beyond it. Its "Insert file" button opens the browser in a popup.
90
+
91
+ ```python
92
+ from filemanager.widgets import HTMLTextarea
93
+
94
+ class PageAdminForm(forms.ModelForm):
95
+ class Meta:
96
+ widgets = {
97
+ 'content': HTMLTextarea(attrs={'rows': 10, 'style': 'width: 95%; max-height: 500px'}),
98
+ }
99
+ ```
100
+
101
+ `admin_site` names the admin site whose browser the button opens, `'admin'` by default. The button is left out where that site's URLs aren't installed. The widget doesn't know the user, so users without file permissions see the button too. The browser then refuses them.
102
+
103
+ ## Settings
104
+
105
+ | Setting | Default | |
106
+ |---|---|---|
107
+ | `FILEMANAGER_STORAGE` | `'default'` | The alias in `STORAGES` of the storage whose files are managed. |
108
+ | `FILEMANAGER_PROTECTED` | `[]` | Paths from the root, such as `'products'`, that are read-only together with everything below them. List the `upload_to` folders of your file fields. |
109
+ | `FILEMANAGER_USAGE_EXCLUDE` | `[]` | App labels (`'django_celery_results'`) or models (`'shop.Order'`) that "where used" doesn't search. |
110
+
111
+ ## Where used
112
+
113
+ The text fields (`TextField`) of every model registered in the admin site are searched for `/` followed by the path, as stored and as it appears in a URL (`a b.jpg` and `a%20b.jpg`). That finds `/media/images/a.jpg`, `https://example.com/media/images/a.jpg` and aliases that keep the end of the path, such as `/images/a.jpg`. A short path at the root can also match a longer one: `/a.jpg` matches `/images/a.jpg`. Each search scans the tables, which is fine for pages opened one at a time. Exclude big tables that hold no links.
114
+
115
+ Rename and move don't change the links. The rename page lists the records to fix.
116
+
117
+ ## Caching
118
+
119
+ Replacing a file keeps its URL, so the URL mustn't be cached for long. Serve the files with a short `max-age`, and with `ETag` or `Last-Modified` so that clients can revalidate. An image cache in front of the files, such as Next.js image optimization, keeps old copies for its own TTL.
120
+
121
+ ## Other storages
122
+
123
+ The views use a store returned by `storage.get_store()`, and `FileSystemStore` is the only one so far. A store for an object storage implements the same methods. Folders are key prefixes there, so renaming one means copying and deleting each object under it, and an empty folder needs a placeholder object. Its `save()` puts the object under its final key, which replaces it in one step.
124
+
125
+ ## Development
126
+
127
+ ### Tests
128
+
129
+ In a project that has the app installed:
130
+
131
+ ```shell
132
+ python manage.py test filemanager
133
+ ```
134
+
135
+ On all supported Python and Django versions, with [tox](https://tox.wiki/):
136
+
137
+ ```shell
138
+ tox
139
+ ```
140
+
141
+ Or once, without a project, on SQLite, in the repository's root:
142
+
143
+ ```shell
144
+ python -m django test filemanager --settings=filemanager.tests.settings
145
+ ```
146
+
147
+ ### Translations
148
+
149
+ The source strings are English, and `filemanager/locale/` holds the English and Russian catalogs. To update them after changing strings, run this in the `filemanager` directory (it needs GNU gettext):
150
+
151
+ ```shell
152
+ django-admin makemessages -l en -l ru
153
+ django-admin compilemessages
154
+ ```
155
+
156
+ ### Releases
157
+
158
+ Set the new version in `pyproject.toml`, commit, then tag the commit and push the tag:
159
+
160
+ ```shell
161
+ git tag v1.0.1
162
+ git push origin v1.0.1
163
+ ```
164
+
165
+ The `publish` workflow tests the tag, publishes it to TestPyPI and PyPI and creates a GitHub release with notes generated from the commits.
166
+
167
+ ## License
168
+
169
+ [MIT](LICENSE)
@@ -0,0 +1,39 @@
1
+ LICENSE
2
+ MANIFEST.in
3
+ README.md
4
+ pyproject.toml
5
+ tox.ini
6
+ django_admin_filemanager.egg-info/PKG-INFO
7
+ django_admin_filemanager.egg-info/SOURCES.txt
8
+ django_admin_filemanager.egg-info/dependency_links.txt
9
+ django_admin_filemanager.egg-info/requires.txt
10
+ django_admin_filemanager.egg-info/top_level.txt
11
+ filemanager/__init__.py
12
+ filemanager/admin.py
13
+ filemanager/apps.py
14
+ filemanager/models.py
15
+ filemanager/storage.py
16
+ filemanager/usage.py
17
+ filemanager/widgets.py
18
+ filemanager/locale/en/LC_MESSAGES/django.mo
19
+ filemanager/locale/en/LC_MESSAGES/django.po
20
+ filemanager/locale/ru/LC_MESSAGES/django.mo
21
+ filemanager/locale/ru/LC_MESSAGES/django.po
22
+ filemanager/migrations/0001_initial.py
23
+ filemanager/migrations/__init__.py
24
+ filemanager/static/filemanager/browse.js
25
+ filemanager/static/filemanager/html_textarea.js
26
+ filemanager/templates/admin/filemanager/base.html
27
+ filemanager/templates/admin/filemanager/browse.html
28
+ filemanager/templates/admin/filemanager/delete.html
29
+ filemanager/templates/admin/filemanager/path.html
30
+ filemanager/templates/admin/filemanager/rename.html
31
+ filemanager/templates/admin/filemanager/usage.html
32
+ filemanager/templates/admin/filemanager/usage_list.html
33
+ filemanager/templates/filemanager/widgets/html_textarea.html
34
+ filemanager/tests/__init__.py
35
+ filemanager/tests/settings.py
36
+ filemanager/tests/test_admin.py
37
+ filemanager/tests/test_storage.py
38
+ filemanager/tests/test_widgets.py
39
+ filemanager/tests/urls.py
File without changes