| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: django-cleanup |
| 3 |
Version: 5.2.0 |
| 4 |
Summary: Deletes old files. |
| 5 |
Home-page: https://github.com/un1t/django-cleanup |
| 6 |
Author: Ilya Shalyapin |
| 7 |
Author-email: [email protected] |
| 8 |
License: MIT License |
| 9 |
Download-URL: https://github.com/un1t/django-cleanup/tarball/master |
| 10 |
Description: Django Cleanup |
| 11 |
************** |
| 12 |
|Version| |Status| |License| |
| 13 |
|
| 14 |
Features |
| 15 |
======== |
| 16 |
The django-cleanup app automatically deletes files for :code:`FileField`, :code:`ImageField` and |
| 17 |
subclasses. When a :code:`FileField`'s value is changed and the model is saved, the old file is |
| 18 |
deleted. When a model that has a :code:`FileField` is deleted, the file is also deleted. A file that |
| 19 |
is set as the :code:`FileField`'s default value will not be deleted. |
| 20 |
|
| 21 |
Compatibility |
| 22 |
------------- |
| 23 |
- Django 2.2, 3.0, 3.1, 3.2 (`See Django Supported Versions <https://www.djangoproject.com/download/#supported-versions>`_) |
| 24 |
- Python 3.5+ |
| 25 |
- Compatible with `sorl-thumbnail <https://github.com/jazzband/sorl-thumbnail>`_ |
| 26 |
- Compatible with `easy-thumbnail <https://github.com/SmileyChris/easy-thumbnails>`_ |
| 27 |
|
| 28 |
How does it work? |
| 29 |
================= |
| 30 |
In order to track changes of a :code:`FileField` and facilitate file deletions, django-cleanup |
| 31 |
connects :code:`post_init`, :code:`pre_save`, :code:`post_save` and :code:`post_delete` signals to |
| 32 |
signal handlers for each :code:`INSTALLED_APPS` model that has a :code:`FileField`. In order to tell |
| 33 |
whether or not a :code:`FileField`'s value has changed a local cache of original values is kept on |
| 34 |
the model instance. If a condition is detected that should result in a file deletion, a function to |
| 35 |
delete the file is setup and inserted into the commit phase of the current transaction. |
| 36 |
|
| 37 |
**Warning! If you are using a database that does not support transactions you may lose files if a |
| 38 |
transaction will rollback at the right instance. This outcome is mitigated by our use of |
| 39 |
post_save and post_delete signals, and by following the recommended configuration below. This |
| 40 |
outcome will still occur if there are signals registered after app initialization and there are |
| 41 |
exceptions when those signals are handled. In this case, the old file will be lost and the new file |
| 42 |
will not be referenced in a model, though the new file will likely still exist on disk. If you are |
| 43 |
concerned about this behavior you will need another solution for old file deletion in your project.** |
| 44 |
|
| 45 |
Installation |
| 46 |
============ |
| 47 |
:: |
| 48 |
|
| 49 |
pip install django-cleanup |
| 50 |
|
| 51 |
|
| 52 |
Configuration |
| 53 |
============= |
| 54 |
Add ``django_cleanup`` to the bottom of ``INSTALLED_APPS`` in ``settings.py`` |
| 55 |
|
| 56 |
.. code-block:: py |
| 57 |
|
| 58 |
INSTALLED_APPS = ( |
| 59 |
..., |
| 60 |
'django_cleanup.apps.CleanupConfig', |
| 61 |
) |
| 62 |
|
| 63 |
That is all, no other configuration is necessary. |
| 64 |
|
| 65 |
Note: Order of ``INSTALLED_APPS`` is important. To ensure that exceptions inside other apps' signal |
| 66 |
handlers do not affect the integrity of file deletions within transactions, ``django_cleanup`` |
| 67 |
should be placed last in ``INSTALLED_APPS``. |
| 68 |
|
| 69 |
Troubleshooting |
| 70 |
=============== |
| 71 |
If you notice that ``django-cleanup`` is not removing files when expected, check that your models |
| 72 |
are being properly |
| 73 |
`loaded <https://docs.djangoproject.com/en/stable/ref/applications/#how-applications-are-loaded>`_: |
| 74 |
|
| 75 |
You must define or import all models in your application's models.py or models/__init__.py. |
| 76 |
Otherwise, the application registry may not be fully populated at this point, which could cause |
| 77 |
the ORM to malfunction. |
| 78 |
|
| 79 |
If your models are not loaded, ``django-cleanup`` will not be able to discover their |
| 80 |
``FileField``'s. |
| 81 |
|
| 82 |
You can check if your ``Model`` is loaded by using |
| 83 |
|
| 84 |
.. code-block:: py |
| 85 |
|
| 86 |
from django.apps import apps |
| 87 |
apps.get_models() |
| 88 |
|
| 89 |
Advanced |
| 90 |
======== |
| 91 |
This section contains additional functionality that can be used to interact with django-cleanup for |
| 92 |
special cases. |
| 93 |
|
| 94 |
Signals |
| 95 |
------- |
| 96 |
To facilitate interactions with other django apps django-cleanup sends the following signals which |
| 97 |
can be imported from :code:`django_cleanup.signals`: |
| 98 |
|
| 99 |
- :code:`cleanup_pre_delete`: just before a file is deleted. Passes a :code:`file` keyword argument. |
| 100 |
- :code:`cleanup_post_delete`: just after a file is deleted. Passes a :code:`file` keyword argument. |
| 101 |
|
| 102 |
Signals example for sorl.thumbnail: |
| 103 |
|
| 104 |
.. code-block:: py |
| 105 |
|
| 106 |
from django_cleanup.signals import cleanup_pre_delete |
| 107 |
from sorl.thumbnail import delete |
| 108 |
|
| 109 |
def sorl_delete(**kwargs): |
| 110 |
delete(kwargs['file']) |
| 111 |
|
| 112 |
cleanup_pre_delete.connect(sorl_delete) |
| 113 |
|
| 114 |
Refresh the cache |
| 115 |
----------------- |
| 116 |
There have been rare cases where the cache would need to be refreshed. To do so the |
| 117 |
:code:`django_cleanup.cleanup.refresh` method can be used: |
| 118 |
|
| 119 |
.. code-block:: py |
| 120 |
|
| 121 |
from django_cleanup import cleanup |
| 122 |
|
| 123 |
cleanup.refresh(model_instance) |
| 124 |
|
| 125 |
Ignore cleanup for a specific model |
| 126 |
----------------------------------- |
| 127 |
Ignore a model and do not perform cleanup when the model is deleted or its files change. |
| 128 |
|
| 129 |
.. code-block:: py |
| 130 |
|
| 131 |
from django_cleanup import cleanup |
| 132 |
|
| 133 |
@cleanup.ignore |
| 134 |
class MyModel(models.Model): |
| 135 |
image = models.FileField() |
| 136 |
|
| 137 |
How to run tests |
| 138 |
================ |
| 139 |
Install, setup and use pyenv_ to install all the required versions of cPython |
| 140 |
(see the `tox.ini <https://github.com/un1t/django-cleanup/blob/master/tox.ini>`_). |
| 141 |
|
| 142 |
Setup pyenv_ to have all versions of python activated within your local django-cleanup repository. |
| 143 |
Ensuring that the python 3.8 that was installed is first priority. |
| 144 |
|
| 145 |
Install tox_ on python 3.8 and run the :code:`tox` command from your local django-cleanup |
| 146 |
repository. |
| 147 |
|
| 148 |
How to write tests |
| 149 |
================== |
| 150 |
This app requires the use of django.test.TransactionTestCase_ when writing tests. |
| 151 |
|
| 152 |
For details on why this is required see `here |
| 153 |
<https://docs.djangoproject.com/en/stable/topics/db/transactions/#use-in-tests>`_: |
| 154 |
|
| 155 |
Django's :code:`TestCase` class wraps each test in a transaction and rolls back that transaction |
| 156 |
after each test, in order to provide test isolation. This means that no transaction is ever |
| 157 |
actually committed, thus your :code:`on_commit()` callbacks will never be run. If you need to |
| 158 |
test the results of an :code:`on_commit()` callback, use a :code:`TransactionTestCase` instead. |
| 159 |
|
| 160 |
License |
| 161 |
======= |
| 162 |
django-cleanup is free software under terms of the: |
| 163 |
|
| 164 |
MIT License |
| 165 |
|
| 166 |
Copyright (C) 2012 by Ilya Shalyapin, [email protected] |
| 167 |
|
| 168 |
Permission is hereby granted, free of charge, to any person obtaining a copy |
| 169 |
of this software and associated documentation files (the "Software"), to deal |
| 170 |
in the Software without restriction, including without limitation the rights |
| 171 |
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 172 |
copies of the Software, and to permit persons to whom the Software is |
| 173 |
furnished to do so, subject to the following conditions: |
| 174 |
|
| 175 |
The above copyright notice and this permission notice shall be included in all |
| 176 |
copies or substantial portions of the Software. |
| 177 |
|
| 178 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 179 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 180 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 181 |
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 182 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 183 |
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 184 |
SOFTWARE. |
| 185 |
|
| 186 |
|
| 187 |
.. _django.test.TransactionTestCase: https://docs.djangoproject.com/en/stable/topics/testing/tools/#django.test.TransactionTestCase |
| 188 |
.. _pyenv: https://github.com/pyenv/pyenv |
| 189 |
.. _tox: https://tox.readthedocs.io/en/latest/ |
| 190 |
|
| 191 |
.. |Version| image:: https://img.shields.io/pypi/v/django-cleanup.svg |
| 192 |
:target: https://pypi.python.org/pypi/django-cleanup/ |
| 193 |
:alt: PyPI Package |
| 194 |
.. |Status| image:: https://travis-ci.org/un1t/django-cleanup.svg?branch=master |
| 195 |
:target: https://travis-ci.org/un1t/django-cleanup |
| 196 |
:alt: Build Status |
| 197 |
.. |License| image:: https://img.shields.io/badge/license-MIT-maroon |
| 198 |
:target: https://github.com/un1t/django-cleanup/blob/master/LICENSE |
| 199 |
:alt: MIT License |
| 200 |
|
| 201 |
Keywords: django |
| 202 |
Platform: UNKNOWN |
| 203 |
Classifier: Development Status :: 5 - Production/Stable |
| 204 |
Classifier: Environment :: Web Environment |
| 205 |
Classifier: Framework :: Django |
| 206 |
Classifier: Framework :: Django :: 2.2 |
| 207 |
Classifier: Framework :: Django :: 3.0 |
| 208 |
Classifier: Framework :: Django :: 3.1 |
| 209 |
Classifier: Framework :: Django :: 3.2 |
| 210 |
Classifier: Intended Audience :: Developers |
| 211 |
Classifier: License :: OSI Approved :: MIT License |
| 212 |
Classifier: Operating System :: OS Independent |
| 213 |
Classifier: Programming Language :: Python |
| 214 |
Classifier: Programming Language :: Python :: 3 |
| 215 |
Classifier: Programming Language :: Python :: 3.5 |
| 216 |
Classifier: Programming Language :: Python :: 3.6 |
| 217 |
Classifier: Programming Language :: Python :: 3.7 |
| 218 |
Classifier: Programming Language :: Python :: 3.8 |
| 219 |
Classifier: Programming Language :: Python :: 3.9 |
| 220 |
Classifier: Programming Language :: Python :: Implementation :: CPython |
| 221 |
Classifier: Programming Language :: Python :: Implementation :: PyPy |
| 222 |
Classifier: Topic :: Utilities |
| 223 |
Requires: python (>=3.5) |
| 224 |
Requires: django (>=2.2) |
| 225 |
Description-Content-Type: text/x-rst |