use dict literal syntax for jinja_options

clarify docs about when jinja_options can be modified

CHANGES.rst

@@ -4,8 +4,8 @@ Flask Changelog
 ===============
 
 
-Version 1.1
------------
+Version 1.1.0
+-------------
 
 Unreleased
 
@@ -24,6 +24,9 @@ Unreleased
     the same thing as "r". :issue:`3163`
 -   The :attr:`MethodView.methods` attribute set in a base class is used
     by subclasses. :issue:`3138`
+-   :attr:`Flask.jinja_options` is a ``dict`` instead of an
+    ``ImmutableDict`` to allow easier configuration. Changes must still
+    be made before creating the environment. :pr:`3190`
 
 .. _#2935: https://github.com/pallets/flask/issues/2935
 .. _#2957: https://github.com/pallets/flask/issues/2957

flask/app.py

@@ -298,10 +298,16 @@ class Flask(_PackageBoundObject):
     #: .. versionadded:: 0.10
     json_decoder = json.JSONDecoder
 
-    #: Options that are passed directly to the Jinja2 environment.
-    jinja_options = dict(
-        extensions=["jinja2.ext.autoescape", "jinja2.ext.with_"]
-    )
+    #: Options that are passed to the Jinja environment in
+    #: :meth:`create_jinja_environment`. Changing these options after
+    #: the environment is created (accessing :attr:`jinja_env`) will
+    #: have no effect.
+    #:
+    #: .. versionchanged:: 1.1.0
+    #:     This is a ``dict`` instead of an ``ImmutableDict`` to allow
+    #:     easier configuration.
+    #:
+    jinja_options = {"extensions": ["jinja2.ext.autoescape", "jinja2.ext.with_"]}
 
     #: Default configuration parameters.
     default_config = ImmutableDict(
@@ -662,7 +668,12 @@ class Flask(_PackageBoundObject):
 
     @locked_cached_property
     def jinja_env(self):
-        """The Jinja2 environment used to load templates."""
+        """The Jinja environment used to load templates.
+
+        The environment is created the first time this property is
+        accessed. Changing :attr:`jinja_options` after that will have no
+        effect.
+        """
         return self.create_jinja_environment()
 
     @property
@@ -739,15 +750,16 @@ class Flask(_PackageBoundObject):
     del _get_templates_auto_reload, _set_templates_auto_reload
 
     def create_jinja_environment(self):
-        """Creates the Jinja2 environment based on :attr:`jinja_options`
-        and :meth:`select_jinja_autoescape`.  Since 0.7 this also adds
-        the Jinja2 globals and filters after initialization.  Override
-        this function to customize the behavior.
+        """Create the Jinja environment based on :attr:`jinja_options`
+        and the various Jinja-related methods of the app. Changing
+        :attr:`jinja_options` after this will have no effect. Also adds
+        Flask-related globals and filters to the environment.
 
-        .. versionadded:: 0.5
         .. versionchanged:: 0.11
            ``Environment.auto_reload`` set in accordance with
            ``TEMPLATES_AUTO_RELOAD`` configuration option.
+
+        .. versionadded:: 0.5
         """
         options = dict(self.jinja_options)