From 7f0fdb51427ffb91f2e7d2d1108afd10551260d0 Mon Sep 17 00:00:00 2001 From: Julien Hartmann Date: Tue, 2 Feb 2016 02:35:19 +0100 Subject: [PATCH] Improve documentation for delete_translations(). Closes #274, #275. --- docs/public/queryset.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/public/queryset.rst b/docs/public/queryset.rst index 3057d701..0ef6f8be 100644 --- a/docs/public/queryset.rst +++ b/docs/public/queryset.rst @@ -90,9 +90,26 @@ delete_translations .. method:: delete_translations() - Deletes all :term:`Translations Model` instances in a queryset, without + Deletes all :term:`Translations Model` instances matched by a queryset, without deleting the :term:`Shared Model` instances. + This can be used to target specific translations of specific objects for deletion. + For instance:: + + # Delete English translation of all objects that have field == "foo" + MyModel.objects.language('en').filter(field='foo').delete_translations() + + # Delete all translations but English for object with id 42 + MyModel.objects.language('all').exclude(language_code='en').filter(pk=42).delete_translations() + + .. warning:: It is an error to delete all translations of an instance. This will + cause the object to be unreachable through translation-aware queries + and invisible in the admin panel. + + If you delete all translations and re-create one immediately after, + remember to enclose the whole process in a transaction to avoid + the possibility of leaving the object unreachable. + .. _select_related-public: select_related