Debian Codegraph @

PKG-INFO

raw
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