Fixed #17085, #24783 -- Refactored template library registration.

* Converted the ``libraries`` and ``builtins`` globals of
  ``django.template.base`` into properties of the Engine class.
* Added a public API for explicit registration of libraries and builtins.

4 files changed, 97 insertions, 4 deletions

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index ec675aada2..c4e414cdb5 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -13,9 +13,11 @@ available to your templates using the :ttag:`{% load %}<load>` tag.
 Code layout
 -----------
 
-Custom template tags and filters must live inside a Django app. If they relate
-to an existing app it makes sense to bundle them there; otherwise, you should
-create a new app to hold them.
+The most common place to specify custom template tags and filters is inside
+a Django app. If they relate to an existing app, it makes sense to bundle them
+there; otherwise, they can be added to a new app. When a Django app is added
+to :setting:`INSTALLED_APPS`, any tags it defines in the conventional location
+described below are automatically made available to load within templates.
 
 The app should contain a ``templatetags`` directory, at the same level as
 ``models.py``, ``views.py``, etc. If this doesn't already exist, create it -
@@ -63,6 +65,15 @@ following::
 
     register = template.Library()
 
+.. versionadded:: 1.9
+
+Alternatively, template tag modules can be registered through the
+``'libraries'`` argument to
+:class:`~django.template.backends.django.DjangoTemplates`. This is useful if
+you want to use a different label from the template tag module name when
+loading template tags. It also enables you to register tags without installing
+an application.
+
 .. admonition:: Behind the scenes
 
     For a ton of examples, read the source code for Django's default filters
diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 4a9a73f758..6ff2dd6c7b 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -41,7 +41,7 @@ lower level APIs:
 Configuring an engine
 =====================
 
-.. class:: Engine([dirs][, app_dirs][, allowed_include_roots][, context_processors][, debug][, loaders][, string_if_invalid][, file_charset])
+.. class:: Engine([dirs][, app_dirs][, allowed_include_roots][, context_processors][, debug][, loaders][, string_if_invalid][, file_charset][, libraries][, builtins])
 
     .. versionadded:: 1.8
 
@@ -114,6 +114,34 @@ Configuring an engine
 
       It defaults to ``'utf-8'``.
 
+    * ``'libraries'``: A dictionary of labels and dotted Python paths of template
+      tag modules to register with the template engine. This is used to add new
+      libraries or provide alternate labels for existing ones. For example::
+
+          Engine(
+              libraries={
+                  'myapp_tags': 'path.to.myapp.tags',
+                  'admin.urls': 'django.contrib.admin.templatetags.admin_urls',
+              },
+          )
+
+      Libraries can be loaded by passing the corresponding dictionary key to
+      the :ttag:`{% load %}<load>` tag.
+
+    * ``'builtins'``: A list of dotted Python paths of template tag modules to
+      add to :doc:`built-ins </ref/templates/builtins>`. For example::
+
+          Engine(
+              builtins=['myapp.builtins'],
+          )
+
+      Tags and filters from built-in libraries can be used without first calling
+      the :ttag:`{% load %}<load>` tag.
+
+.. versionadded:: 1.9
+
+    The ``libraries`` and ``builtins`` arguments were added.
+
 .. staticmethod:: Engine.get_default()
 
     When a Django project configures one and only one
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 76e8085fbd..1aff56aef3 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -263,6 +263,10 @@ Templates
 * :ref:`Debug page integration <template-debug-integration>` for custom
   template engines was added.
 
+* The :class:`~django.template.backends.django.DjangoTemplates` backend gained
+  the ability to register libraries and builtins explicitly through the
+  template :setting:`OPTIONS <TEMPLATES-OPTIONS>`.
+
 Requests and Responses
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -467,6 +471,28 @@ You don't need any of this if you're querying the database through the ORM,
 even if you're using :meth:`raw() <django.db.models.query.QuerySet.raw>`
 queries. The ORM takes care of managing time zone information.
 
+Template tag modules are imported when templates are configured
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :class:`~django.template.backends.django.DjangoTemplates` backend now
+performs discovery on installed template tag modules when instantiated. This
+update enables libraries to be provided explicitly via the ``'libraries'``
+key of :setting:`OPTIONS <TEMPLATES-OPTIONS>` when defining a
+:class:`~django.template.backends.django.DjangoTemplates` backend. Import
+or syntax errors in template tag modules now fail early at instantiation time
+rather than when a template with a :ttag:`{% load %}<load>` tag is first
+compiled.
+
+``django.template.base.add_to_builtins()`` is removed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Although it was a private API, projects commonly used ``add_to_builtins()`` to
+make template tags and filters available without using the
+:ttag:`{% load %}<load>` tag. This API has been formalized. Projects should now
+define built-in libraries via the ``'builtins'`` key of :setting:`OPTIONS
+<TEMPLATES-OPTIONS>` when defining a
+:class:`~django.template.backends.django.DjangoTemplates` backend.
+
 Miscellaneous
 ~~~~~~~~~~~~~
 
diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt
index 3810ea7483..66bb8314d6 100644
--- a/docs/topics/templates.txt
+++ b/docs/topics/templates.txt
@@ -401,6 +401,34 @@ applications. This generic name was kept for backwards-compatibility.
 
   It defaults to the value of :setting:`FILE_CHARSET`.
 
+* ``'libraries'``: A dictionary of labels and dotted Python paths of template
+  tag modules to register with the template engine. This can be used to add
+  new libraries or provide alternate labels for existing ones. For example::
+
+      OPTIONS={
+          'libraries': {
+              'myapp_tags': 'path.to.myapp.tags',
+              'admin.urls': 'django.contrib.admin.templatetags.admin_urls',
+          },
+      }
+
+  Libraries can be loaded by passing the corresponding dictionary key to
+  the :ttag:`{% load %}<load>` tag.
+
+* ``'builtins'``: A list of dotted Python paths of template tag modules to
+  add to :doc:`built-ins </ref/templates/builtins>`. For example::
+
+      OPTIONS={
+          'builtins': ['myapp.builtins'],
+      }
+
+  Tags and filters from built-in libraries can be used without first calling
+  the :ttag:`{% load %} <load>` tag.
+
+.. versionadded:: 1.9
+
+    The ``libraries`` and ``builtins`` arguments were added.
+
 .. module:: django.template.backends.jinja2
 
 .. class:: Jinja2