unify/rename filter and function decoratorsunify-decorators

Use pass_context instead of contextfilter and contextfunction, etc.

2 files changed, 48 insertions, 32 deletions

diff --git a/docs/api.rst b/docs/api.rst
index a012393..8f36f2e 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -591,18 +591,24 @@ Utilities
 These helper functions and classes are useful if you add custom filters or
 functions to a Jinja environment.
 
-.. autofunction:: jinja2.environmentfilter
+.. autofunction:: jinja2.pass_context
+
+.. autofunction:: jinja2.pass_eval_context
+
+.. autofunction:: jinja2.pass_environment
 
 .. autofunction:: jinja2.contextfilter
 
 .. autofunction:: jinja2.evalcontextfilter
 
-.. autofunction:: jinja2.environmentfunction
+.. autofunction:: jinja2.environmentfilter
 
 .. autofunction:: jinja2.contextfunction
 
 .. autofunction:: jinja2.evalcontextfunction
 
+.. autofunction:: jinja2.environmentfunction
+
 .. function:: escape(s)
 
     Convert the characters ``&``, ``<``, ``>``, ``'``, and ``"`` in string `s`
@@ -697,9 +703,9 @@ Some decorators are available to tell Jinja to pass extra information to
 the filter. The object is passed as the first argument, making the value
 being filtered the second argument.
 
--   :func:`environmentfilter` passes the :class:`Environment`.
--   :func:`evalcontextfilter` passes the :ref:`eval-context`.
--   :func:`contextfilter` passes the current
+-   :func:`pass_environment` passes the :class:`Environment`.
+-   :func:`pass_eval_context` passes the :ref:`eval-context`.
+-   :func:`pass_context` passes the current
     :class:`~jinja2.runtime.Context`.
 
 Here's a filter that converts line breaks into HTML ``<br>`` and ``<p>``
@@ -709,10 +715,10 @@ enabled before escaping the input and marking the output safe.
 .. code-block:: python
 
     import re
-    from jinja2 import evalcontextfilter
+    from jinja2 import pass_eval_context
     from markupsafe import Markup, escape
 
-    @evalcontextfilter
+    @pass_eval_context
     def nl2br(eval_ctx, value):
         br = "<br>\n"
 
@@ -775,9 +781,9 @@ Some decorators are available to tell Jinja to pass extra information to
 the filter. The object is passed as the first argument, making the value
 being filtered the second argument.
 
--   :func:`environmentfunction` passes the :class:`Environment`.
--   :func:`evalcontextfunction` passes the :ref:`eval-context`.
--   :func:`contextfunction` passes the current
+-   :func:`pass_environment` passes the :class:`Environment`.
+-   :func:`pass_eval_context` passes the :ref:`eval-context`.
+-   :func:`pass_context` passes the current
     :class:`~jinja2.runtime.Context`.
 
 
@@ -793,37 +799,47 @@ compiled features at runtime.
 Currently it is only used to enable and disable the automatic escaping but
 can be used for extensions as well.
 
-In previous Jinja versions filters and functions were marked as
-environment callables in order to check for the autoescape status from the
-environment.  In new versions it's encouraged to check the setting from the
-evaluation context instead.
+The setting should be checked the evaluation context, not the
+environment. The evaluation context will have the computed value for the
+current template.
 
-Previous versions::
+Instead of ``pass_environment``:
 
-    @environmentfilter
+.. code-block:: python
+
+    @pass_environment
     def filter(env, value):
         result = do_something(value)
+
         if env.autoescape:
             result = Markup(result)
+
         return result
 
-In new versions you can either use a :func:`contextfilter` and access the
-evaluation context from the actual context, or use a
-:func:`evalcontextfilter` which directly passes the evaluation context to
-the function::
+Use ``pass_eval_context`` if you only need the setting:
 
-    @contextfilter
-    def filter(context, value):
+.. code-block:: python
+
+    @pass_eval_context
+    def filter(eval_ctx, value):
         result = do_something(value)
-        if context.eval_ctx.autoescape:
+
+        if eval_ctx.autoescape:
             result = Markup(result)
+
         return result
 
-    @evalcontextfilter
-    def filter(eval_ctx, value):
+Or use ``pass_context`` if you need other context behavior as well:
+
+.. code-block:: python
+
+    @pass_context
+    def filter(context, value):
         result = do_something(value)
-        if eval_ctx.autoescape:
+
+        if context.eval_ctx.autoescape:
             result = Markup(result)
+
         return result
 
 The evaluation context must not be modified at runtime.  Modifications
diff --git a/docs/faq.rst b/docs/faq.rst
index 1e29e12..dd78217 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -113,12 +113,12 @@ CSS, JavaScript, or configuration files.
 Why is the Context immutable?
 -----------------------------
 
-When writing a :func:`contextfunction` or something similar you may have
-noticed that the context tries to stop you from modifying it.  If you have
-managed to modify the context by using an internal context API you may
-have noticed that changes in the context don't seem to be visible in the
-template.  The reason for this is that Jinja uses the context only as
-primary data source for template variables for performance reasons.
+When writing a :func:`pass_context` function, you may have noticed that
+the context tries to stop you from modifying it. If you have managed to
+modify the context by using an internal context API you may have noticed
+that changes in the context don't seem to be visible in the template.
+The reason for this is that Jinja uses the context only as primary data
+source for template variables for performance reasons.
 
 If you want to modify the context write a function that returns a variable
 instead that one can assign to a variable by using set::