| Name | django-nifty-attachments JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | A generic set of template tags to attach files to specific models. |
| upload_time | 2025-08-05 22:44:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4.0,>=3.10 |
| license | MIT License
Copyright (c) 2025 Joseph
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.
|
| keywords |
nifty_attachments
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# django-nifty-attachments
[](https://pypi.python.org/pypi/django-nifty-attachments)  [](https://github.com/powderflask/django-nifty-attachments)
Version: 0.1.1
*"Private" file attachments for a Django Model, with permissions-based access control and without Generic FK.*
> This package is a re-write of [django-attachments](https://github.com/atodorov/django-attachments), originally developed by [atadorov](https://github.com/atodorov).
> `django-nifty-attachments` is free software distributed under the MIT License.
## Adaptations:
Re-wrote app top-to-bottom to accommodate strict access control and remove Generic FK, among others.
1. Removed support for python2 & django<3, delete migrations, delete locale, delete admin, delete management command
2. Remove Generic FK to "related object" , replace with "Model Factory" pattern,
using Abstract Model and dependency inversion instead.
3. Provide injectable permissions with access control for private files
4. Implement "app settings" pattern
Installation:
=============
1. Put `nifty_attachments` to your `INSTALLED_APPS` in your `settings.py`
within your django project (to auto-detect templates and tags):
```
INSTALLED_APPS = (
...
'nifty_attachments',
)
```
2. Define a concrete Attachment model with relation to your related object:
```
class GizmoAttachment(AbstractAttachment.factory("myapp.Gizmo")):
""" A concrete implementation of AbstractAttachment,
with a required FK named `related` to Gizmo with reverse relation "attachment_set"
"""
```
3. Add the attachments urlpattern to your `urls.py`, injecting your concrete attachment model:
```
path(r'^gizmo/attachments/',
include('attachments.urls', namespace='gizmo-attachments', kwargs=dict(model='myapp.GizmoAttachment')),
```
4. Migrate your database:
```
./manage.py migrate
```
5. Grant the user some permissions:
* For **viewing / downloading attachments** grant the user (or group) the permission
`gizmo.view_attachment`.
* For **adding attachments** grant the user (or group) the permission
`gizmo.add_attachment`.
* For **updating attachments** grant the user (or group) the permission
`gizmo.change_attachment`.
* For **deleting own attachments** grant the user (or group) the permission
`gizmo.delete_attachment`. This allows the user to delete their own
attachments only.
* For **updating or deleting any attachments** (including attachments by other users) grant
the user the permission `gizmo.edit_any_attachment`.
Settings
========
* `ATTACHMENTS_FILE_UPLOAD_MAX_SIZE` The maximum upload file size in Mb.
Default: `10 Mb`. Set to `None` for no restriction on file size.
* `ATTACHMENTS_CONTENT_TYPE_WHITELIST` A tuple of http content type strings to allow for upload.
Default: `()`. Set to `()` for no restriction on content type.
Configuration
=============
* configure file upload validators:
* define an iterable of `Callable[[File], ]`;
Validators execute against uploaded `File`. Raise a `ValidationError` to deny the upload.
* configure setting `ATTACHMENTS_FILE_UPLOAD_VALIDATORS` equal to the iterable or a dotted path to it.
E.g. `ATTACHMENTS_FILE_UPLOAD_VALIDATORS = "attachments.validators.default_validators"`
* For custom validators on different Concrete Attachment types, inject custom `form_class` to add view.
* configure permissions: implement the interface defined by `AttachmentPermissionsApi`
and set `permissions = MyAttachmentsPermissions()` on your concrete Attachment Model.
Usage:
======
In your models:
---------------
You must explicitly define a Concrete Attachments model for each related model.
1. use the `factory` method on `AbstractAttachment` to create a base model with a FK to your `related_model`
2. extend this abstract base class, you can add or override any behaviours you like.
3. if you provide a custom `Meta` options, it is highly recommended you extend the base Meta.
```
base_model = AbstractAttachment.factory("myapp.Gizmo")
class GizmoAttachment(base_model):
...
class Meta(base_model.Meta)
...
```
4. You can also inject custom permissions logic with any class that implements `AttachmentPermissions` Protocol.
```
class GizmoPermissions(DefaultAttachmentPermissions):
def can_add_attachments(self, user: User, related_to: "Gizmo") -> bool:
""" Return True iff the user can upload new attachments to the given Gizmo """
return gizmo.permissions.can_change(user, related_to) and super().can_add_attachments(user, related_to)
base_model = AbstractAttachment.factory(
related_model = "myapp.Gizmo",
permissions_class = GizmoPermissions
)
class GizmoAttachment(base_model):
...
```
In your urls:
-------------
You need one namespaced set of attachment urls for each concrete Model.
* Include the `attachments.urls`, supplying an explicit namespace *if your app urls are not namespaced*.
* Inject your concrete Attachment Model, either the Model class or an `app_label.ModelName` string.
```
path('gizmo/attachments/',
include('attachments.urls', namespace='gizmo-attachments'),
kwargs=dict(model='myapp.GizmoAttachment')),
```
To use distinct templates for a specific concrete Attachment type, either
* copy in a url from `attachments.urls`, adding a `template_name` kwarg, to customize an individual view; or
* add at `template_prefix` kwarg to the path include with a template path prefix.
```
path('gizmo/attachments/',
include('attachments.urls', namespace='gizmo-attachments'),
kwargs=dict(model='myapp.GizmoAttachment', template_prefix='gizmo/')),
```
Also, inject `form_class` to `create` and `update` views,
e.g., to customize validation logic for each Concrete Attachment type
In your templates:
------------------
Load the `attachments_tags`:
{% load attachments_tags %}
django-attachments comes with some templatetags to add or delete attachments
for your model objects in your frontend.
1. `get_attachments_for [object]`: Fetches the attachments for the given
model instance. You can optionally define a variable name in which the attachment
list is stored in the template context. If you do not define a variable name, the result is printed instead.
{% get_attachments_for entry as attachments_list %}
2. `attachments_count [object]`: Counts the attachments for the given
model instance and returns an int:
{% attachments_count entry %}
3. `attachment_form`: Renders a upload form to add attachments for the given
model instance. Example:
{% attachment_form [object] %}
It returns an empty string if the current user is not logged in.
4. `attachment_delete_link`: Renders a link to the delete view for the given
*attachment*. Example:
{% for att in attachments_list %}
{{ att }} {% attachment_delete_link att %}
{% endfor %}
This tag automatically checks for permission. It returns only a html link if the
given attachment's creator is the current logged in user or the user has the
`delete_foreign_attachments` permission.
Quick Example:
==============
{% load attachments_tags %}
{% get_attachments_for entry as my_entry_attachments %}
<span>Object has {% attachments_count entry %} attachments</span>
{% if my_entry_attachments %}
<ul>
{% for attachment in my_entry_attachments %}
<li>
<a href="{{ attachment.attachment_file.url }}">{{ attachment.filename }}</a>
{% attachment_delete_link attachment %}
</li>
{% endfor %}
</ul>
{% endif %}
{% attachment_form entry %}
{% if messages %}
<ul class="messages">
{% for message in messages %}
<li{% if message.tags %} class="{{ message.tags }}"{% endif %}>
{{ message }}
</li>
{% endfor %}
</ul>
{% endif %}
Overriding Templates
====================
As usual, templates can be overridden by commandeering the namespace of the default template.
To do this, create a `/nifty/attachments` directory in your app's templates directory,
then override a template by creating a file matching the name of the default template.
Add a folder named for the `template_prefix`, as defined in `urls` config, for attachment type-specific templates.
Settings
========
- `ATTACHMENTS_FILE_UPLOAD_MAX_SIZE` in Mb. Deny file uploads exceeding this value. Default: 10 Mb.
- `ATTACHMENTS_CONTENT_TYPE_WHITELIST` iterable of content type strings. Deny file uploads other than these.
Default: `()` - no restrictions by content type.
- `ATTACHMENTS_FILE_UPLOAD_VALIDATORS` - an iterable of custom file validator functions
executed against each uploaded file. If any of them raises `ValidationError` the upload will be denied.
Default: `nifty_attachments.validators.default_validators`
---
### Acknowledgments
This project would be impossible to maintain without the help of our generous [contributors](https://github.com//graphs/contributors)
#### Technology Colophon
Without django and the django dev team, the universe would have fewer rainbows and ponies.
This package was originally created with [`cookiecutter`](https://www.cookiecutter.io/)
and the [`cookiecutter-powder-pypackage`](https://github.com/JacobTumak/CookiePowder) project template.
---
## Developing?
Check out the [Dev Guide](https://github.com/powderflask/django-nifty-attachments/tree/main/dev-guide.md).
* [GitHub Actions](https://docs.github.com/en/actions) (see [.github/workflows](https://github.com/powderflask/django-nifty-attachments/tree/main/.github/workflows))
### Run Tests
Run the testsuite in your local environment using `pipenv`:
$ cd django-attachments/
$ pipenv install --dev
$ pipenv run pytest attachments/
Raw data
{
"_id": null,
"home_page": null,
"name": "django-nifty-attachments",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "nifty_attachments",
"author": null,
"author_email": "Joseph Fall <jfall@crgl.ca>",
"download_url": "https://files.pythonhosted.org/packages/6c/e1/90cf075bf95ff00d867dd92b08aa08d66d0a894e6e04f20b27fd9bb59c19/django_nifty_attachments-0.1.1.tar.gz",
"platform": null,
"description": "# django-nifty-attachments\n\n\n[](https://pypi.python.org/pypi/django-nifty-attachments)  [](https://github.com/powderflask/django-nifty-attachments)\n\n\nVersion: 0.1.1\n\n*\"Private\" file attachments for a Django Model, with permissions-based access control and without Generic FK.*\n\n> This package is a re-write of [django-attachments](https://github.com/atodorov/django-attachments), originally developed by [atadorov](https://github.com/atodorov).\n\n> `django-nifty-attachments` is free software distributed under the MIT License.\n\n\n\n## Adaptations:\n\nRe-wrote app top-to-bottom to accommodate strict access control and remove Generic FK, among others.\n\n1. Removed support for python2 & django<3, delete migrations, delete locale, delete admin, delete management command\n2. Remove Generic FK to \"related object\" , replace with \"Model Factory\" pattern,\n using Abstract Model and dependency inversion instead.\n3. Provide injectable permissions with access control for private files\n4. Implement \"app settings\" pattern\n\n\nInstallation:\n=============\n\n1. Put `nifty_attachments` to your `INSTALLED_APPS` in your `settings.py`\n within your django project (to auto-detect templates and tags):\n ```\n INSTALLED_APPS = (\n ...\n 'nifty_attachments',\n )\n ```\n\n2. Define a concrete Attachment model with relation to your related object:\n ```\n class GizmoAttachment(AbstractAttachment.factory(\"myapp.Gizmo\")):\n \"\"\" A concrete implementation of AbstractAttachment,\n with a required FK named `related` to Gizmo with reverse relation \"attachment_set\"\n \"\"\"\n ```\n\n3. Add the attachments urlpattern to your `urls.py`, injecting your concrete attachment model:\n ```\n path(r'^gizmo/attachments/',\n include('attachments.urls', namespace='gizmo-attachments', kwargs=dict(model='myapp.GizmoAttachment')),\n ```\n\n4. Migrate your database:\n ```\n ./manage.py migrate\n ```\n\n5. Grant the user some permissions:\n\n * For **viewing / downloading attachments** grant the user (or group) the permission\n `gizmo.view_attachment`.\n\n * For **adding attachments** grant the user (or group) the permission\n `gizmo.add_attachment`.\n\n * For **updating attachments** grant the user (or group) the permission\n `gizmo.change_attachment`.\n\n * For **deleting own attachments** grant the user (or group) the permission\n `gizmo.delete_attachment`. This allows the user to delete their own\n attachments only.\n\n * For **updating or deleting any attachments** (including attachments by other users) grant\n the user the permission `gizmo.edit_any_attachment`.\n\n\nSettings\n========\n\n* `ATTACHMENTS_FILE_UPLOAD_MAX_SIZE` The maximum upload file size in Mb.\n Default: `10 Mb`. Set to `None` for no restriction on file size.\n\n* `ATTACHMENTS_CONTENT_TYPE_WHITELIST` A tuple of http content type strings to allow for upload.\n Default: `()`. Set to `()` for no restriction on content type.\n\n\nConfiguration\n=============\n\n* configure file upload validators:\n * define an iterable of `Callable[[File], ]`;\n Validators execute against uploaded `File`. Raise a `ValidationError` to deny the upload.\n * configure setting `ATTACHMENTS_FILE_UPLOAD_VALIDATORS` equal to the iterable or a dotted path to it.\n E.g. `ATTACHMENTS_FILE_UPLOAD_VALIDATORS = \"attachments.validators.default_validators\"`\n * For custom validators on different Concrete Attachment types, inject custom `form_class` to add view.\n\n* configure permissions: implement the interface defined by `AttachmentPermissionsApi`\n and set `permissions = MyAttachmentsPermissions()` on your concrete Attachment Model.\n\n \nUsage:\n======\n\nIn your models:\n---------------\n\nYou must explicitly define a Concrete Attachments model for each related model.\n1. use the `factory` method on `AbstractAttachment` to create a base model with a FK to your `related_model`\n2. extend this abstract base class, you can add or override any behaviours you like.\n3. if you provide a custom `Meta` options, it is highly recommended you extend the base Meta.\n\n ```\n base_model = AbstractAttachment.factory(\"myapp.Gizmo\")\n class GizmoAttachment(base_model):\n ...\n class Meta(base_model.Meta)\n ...\n ```\n\n4. You can also inject custom permissions logic with any class that implements `AttachmentPermissions` Protocol.\n\n ```\n class GizmoPermissions(DefaultAttachmentPermissions):\n\n def can_add_attachments(self, user: User, related_to: \"Gizmo\") -> bool:\n \"\"\" Return True iff the user can upload new attachments to the given Gizmo \"\"\"\n return gizmo.permissions.can_change(user, related_to) and super().can_add_attachments(user, related_to)\n\n base_model = AbstractAttachment.factory(\n related_model = \"myapp.Gizmo\",\n permissions_class = GizmoPermissions\n )\n class GizmoAttachment(base_model):\n ...\n\n ```\n\nIn your urls:\n-------------\n\nYou need one namespaced set of attachment urls for each concrete Model.\n* Include the `attachments.urls`, supplying an explicit namespace *if your app urls are not namespaced*.\n* Inject your concrete Attachment Model, either the Model class or an `app_label.ModelName` string.\n\n ```\n path('gizmo/attachments/',\n include('attachments.urls', namespace='gizmo-attachments'),\n kwargs=dict(model='myapp.GizmoAttachment')),\n ```\n\nTo use distinct templates for a specific concrete Attachment type, either\n* copy in a url from `attachments.urls`, adding a `template_name` kwarg, to customize an individual view; or\n* add at `template_prefix` kwarg to the path include with a template path prefix.\n\n ```\n path('gizmo/attachments/',\n include('attachments.urls', namespace='gizmo-attachments'),\n kwargs=dict(model='myapp.GizmoAttachment', template_prefix='gizmo/')),\n ```\n\nAlso, inject `form_class` to `create` and `update` views,\ne.g., to customize validation logic for each Concrete Attachment type\n\n\nIn your templates:\n------------------\n\nLoad the `attachments_tags`:\n\n {% load attachments_tags %}\n\ndjango-attachments comes with some templatetags to add or delete attachments\nfor your model objects in your frontend.\n\n1. `get_attachments_for [object]`: Fetches the attachments for the given\n model instance. You can optionally define a variable name in which the attachment\n list is stored in the template context. If you do not define a variable name, the result is printed instead.\n\n {% get_attachments_for entry as attachments_list %}\n\n2. `attachments_count [object]`: Counts the attachments for the given\n model instance and returns an int:\n\n {% attachments_count entry %}\n\n3. `attachment_form`: Renders a upload form to add attachments for the given\n model instance. Example:\n\n {% attachment_form [object] %}\n\n It returns an empty string if the current user is not logged in.\n\n\n4. `attachment_delete_link`: Renders a link to the delete view for the given\n *attachment*. Example:\n\n {% for att in attachments_list %}\n {{ att }} {% attachment_delete_link att %}\n {% endfor %}\n\n This tag automatically checks for permission. It returns only a html link if the\n given attachment's creator is the current logged in user or the user has the\n `delete_foreign_attachments` permission.\n\nQuick Example:\n==============\n\n {% load attachments_tags %}\n {% get_attachments_for entry as my_entry_attachments %}\n\n <span>Object has {% attachments_count entry %} attachments</span>\n {% if my_entry_attachments %}\n <ul>\n {% for attachment in my_entry_attachments %}\n <li>\n <a href=\"{{ attachment.attachment_file.url }}\">{{ attachment.filename }}</a>\n {% attachment_delete_link attachment %}\n </li>\n {% endfor %}\n </ul>\n {% endif %}\n\n {% attachment_form entry %}\n\n {% if messages %}\n <ul class=\"messages\">\n {% for message in messages %}\n <li{% if message.tags %} class=\"{{ message.tags }}\"{% endif %}>\n {{ message }}\n </li>\n {% endfor %}\n </ul>\n {% endif %}\n\n\nOverriding Templates\n====================\n\nAs usual, templates can be overridden by commandeering the namespace of the default template. \nTo do this, create a `/nifty/attachments` directory in your app's templates directory,\nthen override a template by creating a file matching the name of the default template.\nAdd a folder named for the `template_prefix`, as defined in `urls` config, for attachment type-specific templates. \n\nSettings\n========\n\n- `ATTACHMENTS_FILE_UPLOAD_MAX_SIZE` in Mb. Deny file uploads exceeding this value. Default: 10 Mb.\n- `ATTACHMENTS_CONTENT_TYPE_WHITELIST` iterable of content type strings. Deny file uploads other than these.\n Default: `()` - no restrictions by content type.\n- `ATTACHMENTS_FILE_UPLOAD_VALIDATORS` - an iterable of custom file validator functions\n executed against each uploaded file. If any of them raises `ValidationError` the upload will be denied. \n Default: `nifty_attachments.validators.default_validators`\n\n\n\n---\n### Acknowledgments\nThis project would be impossible to maintain without the help of our generous [contributors](https://github.com//graphs/contributors)\n\n#### Technology Colophon\n\nWithout django and the django dev team, the universe would have fewer rainbows and ponies.\n\nThis package was originally created with [`cookiecutter`](https://www.cookiecutter.io/) \nand the [`cookiecutter-powder-pypackage`](https://github.com/JacobTumak/CookiePowder) project template.\n\n---\n\n## Developing?\nCheck out the [Dev Guide](https://github.com/powderflask/django-nifty-attachments/tree/main/dev-guide.md).\n\n * [GitHub Actions](https://docs.github.com/en/actions) (see [.github/workflows](https://github.com/powderflask/django-nifty-attachments/tree/main/.github/workflows))\n\n### Run Tests\n\nRun the testsuite in your local environment using `pipenv`:\n\n $ cd django-attachments/\n $ pipenv install --dev\n $ pipenv run pytest attachments/\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Joseph\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A generic set of template tags to attach files to specific models.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/powderflask/django-nifty-attachments",
"Repository": "https://github.com/powderflask/django-nifty-attachments"
},
"split_keywords": [
"nifty_attachments"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a4062e86ad5d32503686c6d497f42b955ee4aa6b2386fb98a93cf840b24f1acc",
"md5": "34e359cdcb914b1f20214f8548d0a7d1",
"sha256": "ae6c77d85d31d7e3ce92b4f9609744438f21e420c2b43add57b6a1848e7b997a"
},
"downloads": -1,
"filename": "django_nifty_attachments-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34e359cdcb914b1f20214f8548d0a7d1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 21122,
"upload_time": "2025-08-05T22:44:22",
"upload_time_iso_8601": "2025-08-05T22:44:22.704369Z",
"url": "https://files.pythonhosted.org/packages/a4/06/2e86ad5d32503686c6d497f42b955ee4aa6b2386fb98a93cf840b24f1acc/django_nifty_attachments-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6ce190cf075bf95ff00d867dd92b08aa08d66d0a894e6e04f20b27fd9bb59c19",
"md5": "73ac40df48a27a026b8573acc1cdf660",
"sha256": "56ea58c6eb589422b8183b4f4dd2abf196892012f2836ff006b76ba25f51625d"
},
"downloads": -1,
"filename": "django_nifty_attachments-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "73ac40df48a27a026b8573acc1cdf660",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 22531,
"upload_time": "2025-08-05T22:44:24",
"upload_time_iso_8601": "2025-08-05T22:44:24.114803Z",
"url": "https://files.pythonhosted.org/packages/6c/e1/90cf075bf95ff00d867dd92b08aa08d66d0a894e6e04f20b27fd9bb59c19/django_nifty_attachments-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 22:44:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "powderflask",
"github_project": "django-nifty-attachments",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-nifty-attachments"
}
