diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/howto/custom-management-commands.txt | 63 | ||||
| -rw-r--r-- | docs/releases/1.6.txt | 2 | ||||
| -rw-r--r-- | docs/releases/1.8.txt | 2 | ||||
| -rw-r--r-- | docs/releases/2.1.txt | 5 |
4 files changed, 20 insertions, 52 deletions
diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt index d9c929d255..dadbaf9742 100644 --- a/docs/howto/custom-management-commands.txt +++ b/docs/howto/custom-management-commands.txt @@ -126,52 +126,30 @@ such as :option:`--verbosity` and :option:`--traceback`. Management commands and locales =============================== -By default, the :meth:`BaseCommand.execute` method deactivates translations -because some commands shipped with Django perform several tasks (for example, -user-facing content rendering and database population) that require a -project-neutral string language. +By default, management commands are executed with the current active locale. -If, for some reason, your custom management command needs to use a fixed locale, -you should manually activate and deactivate it in your -:meth:`~BaseCommand.handle` method using the functions provided by the I18N -support code:: +If, for some reason, your custom management command must run without an active +locale (for example, to prevent translated content from being inserted into +the database), deactivate translations using the ``@no_translations`` +decorator on your :meth:`~BaseCommand.handle` method:: - from django.core.management.base import BaseCommand, CommandError - from django.utils import translation + from django.core.management.base import BaseCommand, no_translations class Command(BaseCommand): ... + @no_translations def handle(self, *args, **options): - - # Activate a fixed locale, e.g. Russian - translation.activate('ru') - - # Or you can activate the LANGUAGE_CODE # chosen in the settings: - from django.conf import settings - translation.activate(settings.LANGUAGE_CODE) - - # Your command logic here ... - translation.deactivate() - -Another need might be that your command simply should use the locale set in -settings and Django should be kept from deactivating it. You can achieve -it by using the :data:`BaseCommand.leave_locale_alone` option. +Since translation deactivation requires access to configured settings, the +decorator can't be used for commands that work without configured settings. -When working on the scenarios described above though, take into account that -system management commands typically have to be very careful about running in -non-uniform locales, so you might need to: +.. versionchanged:: 2.1 -* Make sure the :setting:`USE_I18N` setting is always ``True`` when running - the command (this is a good example of the potential problems stemming - from a dynamic runtime environment that Django commands avoid offhand by - deactivating translations). - -* Review the code of your command and the code it calls for behavioral - differences when locales are changed and evaluate its impact on - predictable behavior of your command. + The ``@no_translations`` decorator is new. In older versions, translations + are deactivated before running a command unless the command's + ``leave_locale_alone`` attribute (now removed) is set to ``True``. Testing ======= @@ -247,21 +225,6 @@ All attributes can be set in your derived class and can be used in A boolean; if ``True``, the entire Django project will be checked for potential problems prior to executing the command. Default value is ``True``. -.. attribute:: BaseCommand.leave_locale_alone - - A boolean indicating whether the locale set in settings should be preserved - during the execution of the command instead of translations being - deactivated. - - Default value is ``False``. - - Make sure you know what you are doing if you decide to change the value of - this option in your custom command if it creates database content that - is locale-sensitive and such content shouldn't contain any translations - (like it happens e.g. with :mod:`django.contrib.auth` permissions) as - activating any locale might cause unintended effects. See the `Management - commands and locales`_ section above for further details. - .. attribute:: BaseCommand.style An instance attribute that helps create colored output when writing to diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index f878c29d48..00d099b025 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -193,7 +193,7 @@ Minor features option is now performed independently from handling of the locale that should be active during the execution of the command. The latter can now be influenced by the new - :attr:`~django.core.management.BaseCommand.leave_locale_alone` internal + ``BaseCommand.leave_locale_alone`` internal option. See :ref:`management-commands-and-locales` for more details. * The :attr:`~django.views.generic.edit.DeletionMixin.success_url` of diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index a122b52666..73d147ad35 100644 --- a/docs/releases/1.8.txt +++ b/docs/releases/1.8.txt @@ -1166,7 +1166,7 @@ Miscellaneous that Django includes) will no longer convert null values back to an empty string. This is consistent with other backends. -* When the :attr:`~django.core.management.BaseCommand.leave_locale_alone` +* When the ``BaseCommand.leave_locale_alone`` attribute is ``False``, translations are now deactivated instead of forcing the "en-us" locale. In the case your models contained non-English strings and you counted on English translations to be activated in management commands, diff --git a/docs/releases/2.1.txt b/docs/releases/2.1.txt index 5f23d6d241..efa2b468c7 100644 --- a/docs/releases/2.1.txt +++ b/docs/releases/2.1.txt @@ -418,6 +418,11 @@ Miscellaneous * The database router :meth:`allow_relation` method is called in more cases. Improperly written routers may need to be updated accordingly. +* Translations are no longer deactivated before running management commands. + If your custom command requires translations to be deactivated (for example, + to insert untranslated content into the database), use the new + :ref:`@no_translations decorator <management-commands-and-locales>`. + .. _deprecated-features-2.1: Features deprecated in 2.1 |