diff options
| author | Carlton Gibson <carlton.gibson@noumenal.co.uk> | 2017-03-10 21:46:37 +0100 |
|---|---|---|
| committer | Tim Graham <timograham@gmail.com> | 2017-03-31 17:26:42 -0400 |
| commit | 6b3724fa1116c0949a6e0cd3e0dd55959a3abd93 (patch) | |
| tree | 15ec6884e5cf6aab1e8ae2eb0be1af3805283519 /docs | |
| parent | 70197241017575b60973b038c8f68dcb18526110 (diff) | |
Fixed #27359 -- Made Engine.get_default() return the first DjangoTemplates engine if multiple are defined.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ref/templates/api.txt | 20 | ||||
| -rw-r--r-- | docs/releases/2.0.txt | 4 |
2 files changed, 17 insertions, 7 deletions
diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 2efbedbdc2..e8d140910d 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -146,14 +146,20 @@ what's passed by :class:`~django.template.backends.django.DjangoTemplates`. .. staticmethod:: Engine.get_default() - When a Django project configures one and only one - :class:`~django.template.backends.django.DjangoTemplates` engine, this - method returns the underlying :class:`Engine`. In other circumstances it - will raise :exc:`~django.core.exceptions.ImproperlyConfigured`. + Returns the underlying :class:`Engine` from the first configured + :class:`~django.template.backends.django.DjangoTemplates` engine. Raises + :exc:`~django.core.exceptions.ImproperlyConfigured` if no engines are + configured. It's required for preserving APIs that rely on a globally available, implicitly configured engine. Any other use is strongly discouraged. + .. versionchanged:: 2.0 + + In older versions, raises + :exc:`~django.core.exceptions.ImproperlyConfigured` if multiple + engines are configured rather than returning the first engine. + .. method:: Engine.from_string(template_code) Compiles the given template code and returns a :class:`Template` object. @@ -175,9 +181,11 @@ The recommended way to create a :class:`Template` is by calling the factory methods of the :class:`Engine`: :meth:`~Engine.get_template`, :meth:`~Engine.select_template` and :meth:`~Engine.from_string`. -In a Django project where the :setting:`TEMPLATES` setting defines exactly one +In a Django project where the :setting:`TEMPLATES` setting defines a :class:`~django.template.backends.django.DjangoTemplates` engine, it's -possible to instantiate a :class:`Template` directly. +possible to instantiate a :class:`Template` directly. If more than one +:class:`~django.template.backends.django.DjangoTemplates` engine is defined, +the first one will be used. .. class:: Template diff --git a/docs/releases/2.0.txt b/docs/releases/2.0.txt index 369a5893ba..ee2117546b 100644 --- a/docs/releases/2.0.txt +++ b/docs/releases/2.0.txt @@ -191,7 +191,9 @@ Signals Templates ~~~~~~~~~ -* ... +* To increase the usefulness of :meth:`.Engine.get_default` in third-party + apps, it now returns the first engine if multiple ``DjangoTemplates`` engines + are configured in ``TEMPLATES`` rather than raising ``ImproperlyConfigured``. Tests ~~~~~ |