Use pass_context instead of contextfilter and contextfunction, etc.
- Add ``is filter`` and ``is test`` tests to test if a name is a
registered filter or test. This allows checking if a filter is
available in a template before using it. Test functions can be
- decorated with ``@environmentfunction``, ``@evalcontextfunction``,
- or ``@contextfunction``. :issue:`842`, :pr:`1248`
+ decorated with ``@pass_environment``, ``@pass_eval_context``,
+ or ``@pass_context``. :issue:`842`, :pr:`1248`
- Support ``pgettext`` and ``npgettext`` (message contexts) in i18n
extension. :issue:`441`
- The ``|indent`` filter's ``width`` argument can be a string to
breaks. Other characters are left unchanged. :issue:`769, 952, 1313`
- ``|groupby`` filter takes an optional ``default`` argument.
:issue:`1359`
+- The function and filter decorators have been renamed and unified.
+ The old names are deprecated. :issue:`1381`
+
+ - ``pass_context`` replaces ``contextfunction`` and
+ ``contextfilter``.
+ - ``pass_eval_context`` replaces ``evalcontextfunction`` and
+ ``evalcontextfilter``
+ - ``pass_environment`` replaces ``environmentfunction`` and
+ ``environmentfilter``.
Version 2.11.3
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`
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>``
.. 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"
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`.
Evaluation Context
------------------
-The evaluation context (short eval context or eval ctx) is a new object
-introduced in Jinja 2.4 that makes it possible to activate and deactivate
-compiled features at runtime.
+The evaluation context (short eval context or eval ctx) makes it
+possible to activate and deactivate compiled features at runtime.
-Currently it is only used to enable and disable the automatic escaping but
-can be used for extensions as well.
+Currently it is only used to enable and disable automatic escaping, but
+it can be used by 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 ``autoescape`` setting should be checked on 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
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::
from .utils import environmentfunction
from .utils import evalcontextfunction
from .utils import is_undefined
+from .utils import pass_context
+from .utils import pass_environment
+from .utils import pass_eval_context
from .utils import select_autoescape
__version__ = "3.0.0a1"
import typing
import typing as t
+import warnings
from functools import wraps
from itertools import groupby
from . import filters
from .asyncsupport import auto_aiter
from .asyncsupport import auto_await
+from .utils import _PassArg
+from .utils import pass_eval_context
if t.TYPE_CHECKING:
from .environment import Environment
yield item
-def dualfilter(normal_filter, async_filter):
- wrap_evalctx = False
+def dual_filter(normal_func, async_func):
+ pass_arg = _PassArg.from_obj(normal_func)
+ wrapper_has_eval_context = False
- if getattr(normal_filter, "environmentfilter", False) is True:
+ if pass_arg is _PassArg.environment:
+ wrapper_has_eval_context = False
def is_async(args):
return args[0].is_async
- wrap_evalctx = False
else:
- has_evalctxfilter = getattr(normal_filter, "evalcontextfilter", False) is True
- has_ctxfilter = getattr(normal_filter, "contextfilter", False) is True
- wrap_evalctx = not has_evalctxfilter and not has_ctxfilter
+ wrapper_has_eval_context = pass_arg is None
def is_async(args):
return args[0].environment.is_async
- @wraps(normal_filter)
+ @wraps(normal_func)
def wrapper(*args, **kwargs):
b = is_async(args)
- if wrap_evalctx:
+ if wrapper_has_eval_context:
args = args[1:]
if b:
- return async_filter(*args, **kwargs)
+ return async_func(*args, **kwargs)
- return normal_filter(*args, **kwargs)
+ return normal_func(*args, **kwargs)
- if wrap_evalctx:
- wrapper.evalcontextfilter = True
+ if wrapper_has_eval_context:
+ wrapper = pass_eval_context(wrapper)
- wrapper.asyncfiltervariant = True
+ wrapper.jinja_async_variant = True
return wrapper
-def asyncfiltervariant(original):
+def async_variant(original):
def decorator(f):
- return dualfilter(original, f)
+ return dual_filter(original, f)
return decorator
-@asyncfiltervariant(filters.do_first)
+def asyncfiltervariant(original):
+ warnings.warn(
+ "'asyncfiltervariant' is renamed to 'async_variant', the old"
+ " name will be removed in Jinja 3.1.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ return async_variant(original)
+
+
+@async_variant(filters.do_first)
async def do_first(
environment: "Environment", seq: "t.Union[t.AsyncIterable[V], t.Iterable[V]]"
) -> "t.Union[V, Undefined]":
return environment.undefined("No first item, sequence was empty.")
-@asyncfiltervariant(filters.do_groupby)
+@async_variant(filters.do_groupby)
async def do_groupby(
environment: "Environment",
value: "t.Union[t.AsyncIterable[V], t.Iterable[V]]",
]
-@asyncfiltervariant(filters.do_join)
+@async_variant(filters.do_join)
async def do_join(
eval_ctx: "EvalContext",
value: t.Union[t.AsyncIterable, t.Iterable],
return filters.do_join(eval_ctx, await auto_to_seq(value), d, attribute)
-@asyncfiltervariant(filters.do_list)
+@async_variant(filters.do_list)
async def do_list(value: "t.Union[t.AsyncIterable[V], t.Iterable[V]]") -> "t.List[V]":
return await auto_to_seq(value)
-@asyncfiltervariant(filters.do_reject)
+@async_variant(filters.do_reject)
async def do_reject(
context: "Context",
value: "t.Union[t.AsyncIterable[V], t.Iterable[V]]",
return async_select_or_reject(context, value, args, kwargs, lambda x: not x, False)
-@asyncfiltervariant(filters.do_rejectattr)
+@async_variant(filters.do_rejectattr)
async def do_rejectattr(
context: "Context",
value: "t.Union[t.AsyncIterable[V], t.Iterable[V]]",
return async_select_or_reject(context, value, args, kwargs, lambda x: not x, True)
-@asyncfiltervariant(filters.do_select)
+@async_variant(filters.do_select)
async def do_select(
context: "Context",
value: "t.Union[t.AsyncIterable[V], t.Iterable[V]]",
return async_select_or_reject(context, value, args, kwargs, lambda x: x, False)
-@asyncfiltervariant(filters.do_selectattr)
+@async_variant(filters.do_selectattr)
async def do_selectattr(
context: "Context",
value: "t.Union[t.AsyncIterable[V], t.Iterable[V]]",
...
-@asyncfiltervariant(filters.do_map)
+@async_variant(filters.do_map)
async def do_map(context, value, *args, **kwargs):
if value:
func = filters.prepare_map(context, args, kwargs)
yield await auto_await(func(item))
-@asyncfiltervariant(filters.do_sum)
+@async_variant(filters.do_sum)
async def do_sum(
environment: "Environment",
iterable: "t.Union[t.AsyncIterable[V], t.Iterable[V]]",
return rv
-@asyncfiltervariant(filters.do_slice)
+@async_variant(filters.do_slice)
async def do_slice(
value: "t.Union[t.AsyncIterable[V], t.Iterable[V]]",
slices: int,
from .idtracking import VAR_LOAD_UNDEFINED
from .nodes import EvalContext
from .optimizer import Optimizer
+from .utils import _PassArg
from .utils import concat
from .visitor import NodeVisitor
if self.environment.finalize:
src = "environment.finalize("
env_finalize = self.environment.finalize
+ pass_arg = {
+ _PassArg.context: "context",
+ _PassArg.eval_context: "context.eval_ctx",
+ _PassArg.environment: "environment",
+ }.get(_PassArg.from_obj(env_finalize))
+ finalize = None
- def finalize(value):
- return default(env_finalize(value))
-
- if getattr(env_finalize, "contextfunction", False) is True:
- src += "context, "
- finalize = None # noqa: F811
- elif getattr(env_finalize, "evalcontextfunction", False) is True:
- src += "context.eval_ctx, "
- finalize = None
- elif getattr(env_finalize, "environmentfunction", False) is True:
- src += "environment, "
+ if pass_arg is None:
def finalize(value):
- return default(env_finalize(self.environment, value))
+ return default(env_finalize(value))
+
+ else:
+ src = f"{src}{pass_arg}, "
+
+ if pass_arg == "environment":
+
+ def finalize(value):
+ return default(env_finalize(self.environment, value))
self._finalize = self._FinalizeInfo(finalize, src)
return self._finalize
if is_filter:
compiler_map = self.filters
env_map = self.environment.filters
- type_name = mark_name = "filter"
+ type_name = "filter"
else:
compiler_map = self.tests
env_map = self.environment.tests
type_name = "test"
- # Filters use "contextfilter", tests and calls use "contextfunction".
- mark_name = "function"
if self.environment.is_async:
self.write("await auto_await(")
if func is None and not frame.soft_frame:
self.fail(f"No {type_name} named {node.name!r}.", node.lineno)
- if getattr(func, f"context{mark_name}", False) is True:
- self.write("context, ")
- elif getattr(func, f"evalcontext{mark_name}", False) is True:
- self.write("context.eval_ctx, ")
- elif getattr(func, f"environment{mark_name}", False) is True:
- self.write("environment, ")
+ pass_arg = {
+ _PassArg.context: "context",
+ _PassArg.eval_context: "context.eval_ctx",
+ _PassArg.environment: "environment",
+ }.get(_PassArg.from_obj(func))
+
+ if pass_arg is not None:
+ self.write(f"{pass_arg}, ")
# Back to the visitor function to handle visiting the target of
# the filter or test.
from .runtime import Context
from .runtime import new_context
from .runtime import Undefined
+from .utils import _PassArg
from .utils import concat
from .utils import consume
from .utils import have_async_gen
):
if is_filter:
env_map = self.filters
- type_name = mark_name = "filter"
+ type_name = "filter"
else:
env_map = self.tests
type_name = "test"
- # Filters use "contextfilter", tests and calls use "contextfunction".
- mark_name = "function"
func = env_map.get(name)
args = [value, *(args if args is not None else ())]
kwargs = kwargs if kwargs is not None else {}
+ pass_arg = _PassArg.from_obj(func)
- if getattr(func, f"context{mark_name}", False) is True:
+ if pass_arg is _PassArg.context:
if context is None:
raise TemplateRuntimeError(
f"Attempted to invoke a context {type_name} without context."
)
args.insert(0, context)
- elif getattr(func, f"evalcontext{mark_name}", False) is True:
+ elif pass_arg is _PassArg.eval_context:
if eval_ctx is None:
if context is not None:
eval_ctx = context.eval_ctx
eval_ctx = EvalContext(self)
args.insert(0, eval_ctx)
- elif getattr(func, f"environment{mark_name}", False) is True:
+ elif pass_arg is _PassArg.environment:
args.insert(0, self)
return func(*args, **kwargs)
It's your responsibility to await this if needed.
.. versionchanged:: 3.0
- Tests support ``@contextfunction``, etc. decorators. Added
+ Tests support ``@pass_context``, etc. decorators. Added
the ``context`` and ``eval_ctx`` parameters.
.. versionadded:: 2.7
from .exceptions import TemplateSyntaxError
from .nodes import ContextReference
from .runtime import concat
-from .utils import contextfunction
from .utils import import_string
+from .utils import pass_context
# I18N functions available in Jinja templates. If the I18N library
# provides ugettext, it will be assigned to gettext.
)
-@contextfunction
+@pass_context
def _gettext_alias(__context, *args, **kwargs):
return __context.call(__context.resolve("gettext"), *args, **kwargs)
def _make_new_gettext(func):
- @contextfunction
+ @pass_context
def gettext(__context, __string, **variables):
rv = __context.call(func, __string)
if __context.eval_ctx.autoescape:
def _make_new_ngettext(func):
- @contextfunction
+ @pass_context
def ngettext(__context, __singular, __plural, __num, **variables):
variables.setdefault("num", __num)
rv = __context.call(func, __singular, __plural, __num)
def _make_new_pgettext(func):
- @contextfunction
+ @pass_context
def pgettext(__context, __string_ctx, __string, **variables):
variables.setdefault("context", __string_ctx)
rv = __context.call(func, __string_ctx, __string)
def _make_new_npgettext(func):
- @contextfunction
+ @pass_context
def npgettext(__context, __string_ctx, __singular, __plural, __num, **variables):
variables.setdefault("context", __string_ctx)
variables.setdefault("num", __num)
import re
import typing
import typing as t
+import warnings
from collections import abc
from itertools import chain
from itertools import groupby
from .exceptions import FilterArgumentError
from .runtime import Undefined
from .utils import htmlsafe_json_dumps
+from .utils import pass_context
+from .utils import pass_environment
+from .utils import pass_eval_context
from .utils import pformat
from .utils import url_quote
from .utils import urlize
K = t.TypeVar("K")
V = t.TypeVar("V")
- F = t.TypeVar("F", bound=t.Callable[..., t.Any])
class HasHTML(te.Protocol):
def __html__(self) -> str:
pass
-def contextfilter(f: "F") -> "F":
- """Decorator for marking context dependent filters. The current
- :class:`Context` will be passed as first argument.
+def contextfilter(f):
+ """Pass the context as the first argument to the decorated function.
+
+ .. deprecated:: 3.0.0
+ Use :func:`~jinja2.pass_context` instead.
"""
- f.contextfilter = True # type: ignore
- return f
+ warnings.warn(
+ "'contextfilter' is renamed to 'pass_context', the old name"
+ " will be removed in Jinja 3.1.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ return pass_context(f)
+
+def evalcontextfilter(f):
+ """Pass the eval context as the first argument to the decorated
+ function.
-def evalcontextfilter(f: "F") -> "F":
- """Decorator for marking eval-context dependent filters. An eval
- context object is passed as first argument. For more information
- about the eval context, see :ref:`eval-context`.
+ .. deprecated:: 3.0.0
+ Use :func:`~jinja2.pass_eval_context` instead.
.. versionadded:: 2.4
"""
- f.evalcontextfilter = True # type: ignore
- return f
+ warnings.warn(
+ "'evalcontextfilter' is renamed to 'pass_eval_context', the old"
+ " name will be removed in Jinja 3.1.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ return pass_eval_context(f)
+
+def environmentfilter(f):
+ """Pass the environment as the first argument to the decorated
+ function.
-def environmentfilter(f: "F") -> "F":
- """Decorator for marking environment dependent filters. The current
- :class:`Environment` is passed to the filter as first argument.
+ .. deprecated:: 3.0.0
+ Use :func:`~jinja2.pass_environment` instead.
"""
- f.environmentfilter = True # type: ignore
- return f
+ warnings.warn(
+ "'environmentfilter' is renamed to 'pass_environment', the old"
+ " name will be removed in Jinja 3.1.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ return pass_environment(f)
def ignore_case(value: "V") -> "V":
)
-@evalcontextfilter
+@pass_eval_context
def do_replace(
eval_ctx: "EvalContext", s: str, old: str, new: str, count: t.Optional[int] = None
) -> str:
return soft_str(s).lower()
-@evalcontextfilter
+@pass_eval_context
def do_xmlattr(
eval_ctx: "EvalContext", d: t.Mapping[str, t.Any], autospace: bool = True
) -> str:
return sorted(value.items(), key=sort_func, reverse=reverse)
-@environmentfilter
+@pass_environment
def do_sort(
environment: "Environment",
value: "t.Iterable[V]",
return sorted(value, key=key_func, reverse=reverse)
-@environmentfilter
+@pass_environment
def do_unique(
environment: "Environment",
value: "t.Iterable[V]",
return func(chain([first], it), key=key_func)
-@environmentfilter
+@pass_environment
def do_min(
environment: "Environment",
value: "t.Iterable[V]",
return _min_or_max(environment, value, min, case_sensitive, attribute)
-@environmentfilter
+@pass_environment
def do_max(
environment: "Environment",
value: "t.Iterable[V]",
return value
-@evalcontextfilter
+@pass_eval_context
def do_join(
eval_ctx: "EvalContext",
value: t.Iterable,
return soft_str(value).center(width)
-@environmentfilter
+@pass_environment
def do_first(
environment: "Environment", seq: "t.Iterable[V]"
) -> "t.Union[V, Undefined]":
return environment.undefined("No first item, sequence was empty.")
-@environmentfilter
+@pass_environment
def do_last(
environment: "Environment", seq: "t.Reversible[V]"
) -> "t.Union[V, Undefined]":
return environment.undefined("No last item, sequence was empty.")
-@contextfilter
+@pass_context
def do_random(context: "Context", seq: "t.Sequence[V]") -> "t.Union[V, Undefined]":
"""Return a random item from the sequence."""
try:
_uri_scheme_re = re.compile(r"^([\w.+-]{2,}:(/){0,2})$")
-@evalcontextfilter
+@pass_eval_context
def do_urlize(
eval_ctx: "EvalContext",
value: str,
return rv
-@environmentfilter
+@pass_environment
def do_truncate(
env: "Environment",
s: str,
return result + end
-@environmentfilter
+@pass_environment
def do_wordwrap(
environment: "Environment",
s: str,
return tuple.__str__(self)
-@environmentfilter
+@pass_environment
def do_groupby(
environment: "Environment",
value: "t.Iterable[V]",
]
-@environmentfilter
+@pass_environment
def do_sum(
environment: "Environment",
iterable: "t.Iterable[V]",
raise FilterArgumentError("argument must be iterable")
-@environmentfilter
+@pass_environment
def do_attr(
environment: "Environment", obj: t.Any, name: str
) -> t.Union[Undefined, t.Any]:
...
-@contextfilter
+@pass_context
def do_map(context, value, *args, **kwargs):
"""Applies a filter on a sequence of objects or looks up an attribute.
This is useful when dealing with lists of objects but you are really
yield func(item)
-@contextfilter
+@pass_context
def do_select(
context: "Context", value: "t.Iterable[V]", *args: t.Any, **kwargs: t.Any
) -> "t.Iterator[V]":
return select_or_reject(context, value, args, kwargs, lambda x: x, False)
-@contextfilter
+@pass_context
def do_reject(
context: "Context", value: "t.Iterable[V]", *args: t.Any, **kwargs: t.Any
) -> "t.Iterator[V]":
return select_or_reject(context, value, args, kwargs, lambda x: not x, False)
-@contextfilter
+@pass_context
def do_selectattr(
context: "Context", value: "t.Iterable[V]", *args: t.Any, **kwargs: t.Any
) -> "t.Iterator[V]":
return select_or_reject(context, value, args, kwargs, lambda x: x, True)
-@contextfilter
+@pass_context
def do_rejectattr(
context: "Context", value: "t.Iterable[V]", *args: t.Any, **kwargs: t.Any
) -> "t.Iterator[V]":
return select_or_reject(context, value, args, kwargs, lambda x: not x, True)
-@evalcontextfilter
+@pass_eval_context
def do_tojson(
eval_ctx: "EvalContext", value: t.Any, indent: t.Optional[int] = None
) -> Markup:
from markupsafe import Markup
+from .utils import _PassArg
+
_binop_to_func = {
"*": operator.mul,
"/": operator.truediv,
if self._is_filter:
env_map = eval_ctx.environment.filters
- mark_name = "filter"
else:
env_map = eval_ctx.environment.tests
- # Filters use "contextfilter", tests and calls use "contextfunction".
- mark_name = "function"
func = env_map.get(self.name)
+ pass_arg = _PassArg.from_obj(func)
- if func is None or getattr(func, f"context{mark_name}", False) is True:
+ if func is None or pass_arg is _PassArg.context:
raise Impossible()
if eval_ctx.environment.is_async and (
- getattr(func, f"async{mark_name}variant", False)
+ getattr(func, "jinja_async_variant", False) is True
or inspect.iscoroutinefunction(func)
):
raise Impossible()
args, kwargs = args_as_const(self, eval_ctx)
args.insert(0, self.node.as_const(eval_ctx))
- if getattr(func, f"evalcontext{mark_name}", False) is True:
+ if pass_arg is _PassArg.eval_context:
args.insert(0, eval_ctx)
- elif getattr(func, f"environment{mark_name}", False) is True:
+ elif pass_arg is _PassArg.environment:
args.insert(0, eval_ctx.environment)
try:
.. versionchanged:: 3.0
``as_const`` shares the same logic for filters and tests. Tests
- check for volatile, async, and ``@contextfunction`` etc.
+ check for volatile, async, and ``@pass_context`` etc.
decorators.
"""
Getattr(ContextReference(), 'name'))
This is basically equivalent to using the
- :func:`~jinja2.contextfunction` decorator when using the
- high-level API, which causes a reference to the context to be passed
- as the first argument to a function.
+ :func:`~jinja2.pass_context` decorator when using the high-level
+ API, which causes a reference to the context to be passed as the
+ first argument to a function.
"""
from .exceptions import TemplateRuntimeError # noqa: F401
from .exceptions import UndefinedError
from .nodes import EvalContext
+from .utils import _PassArg
from .utils import concat
-from .utils import evalcontextfunction
from .utils import internalcode
from .utils import missing
from .utils import Namespace # noqa: F401
from .utils import object_type_repr
+from .utils import pass_eval_context
if t.TYPE_CHECKING:
from .environment import Environment
The context is immutable. Modifications on :attr:`parent` **must not**
happen and modifications on :attr:`vars` are allowed from generated
template code only. Template filters and global functions marked as
- :func:`contextfunction`\\s get the active context passed as first argument
+ :func:`pass_context` get the active context passed as first argument
and are allowed to access the context read-only.
The template context supports read only dict operations (`get`,
def call(__self, __obj, *args, **kwargs): # noqa: B902
"""Call the callable with the arguments and keyword arguments
provided but inject the active context or environment as first
- argument if the callable is a :func:`contextfunction` or
- :func:`environmentfunction`.
+ argument if the callable has :func:`pass_context` or
+ :func:`pass_environment`.
"""
if __debug__:
__traceback_hide__ = True # noqa
# Allow callable classes to take a context
- if hasattr(__obj, "__call__"): # noqa: B004
- fn = __obj.__call__
- for fn_type in (
- "contextfunction",
- "evalcontextfunction",
- "environmentfunction",
- ):
- if hasattr(fn, fn_type):
- __obj = fn
- break
+ if (
+ hasattr(__obj, "__call__") # noqa: B004
+ and _PassArg.from_obj(__obj.__call__) is not None
+ ):
+ __obj = __obj.__call__
if callable(__obj):
- if getattr(__obj, "contextfunction", False) is True:
+ pass_arg = _PassArg.from_obj(__obj)
+
+ if pass_arg is _PassArg.context:
# the active context should have access to variables set in
# loops and blocks without mutating the context itself
if kwargs.get("_loop_vars"):
if kwargs.get("_block_vars"):
__self = __self.derived(kwargs["_block_vars"])
args = (__self,) + args
- elif getattr(__obj, "evalcontextfunction", False) is True:
+ elif pass_arg is _PassArg.eval_context:
args = (__self.eval_ctx,) + args
- elif getattr(__obj, "environmentfunction", False) is True:
+ elif pass_arg is _PassArg.environment:
args = (__self.environment,) + args
kwargs.pop("_block_vars", None)
self._default_autoescape = default_autoescape
@internalcode
- @evalcontextfunction
+ @pass_eval_context
def __call__(self, *args, **kwargs):
# This requires a bit of explanation, In the past we used to
# decide largely based on compile-time information if a macro is
from numbers import Number
from .runtime import Undefined
-from .utils import environmentfunction
+from .utils import pass_environment
if t.TYPE_CHECKING:
from .environment import Environment
return isinstance(value, Undefined)
-@environmentfunction
+@pass_environment
def test_filter(env: "Environment", value: str) -> bool:
"""Check if a filter exists by name. Useful if a filter may be
optionally available.
return value in env.filters
-@environmentfunction
+@pass_environment
def test_test(env: "Environment", value: str) -> bool:
"""Check if a test exists by name. Useful if a test may be
optionally available.
+import enum
import json
import os
import re
import typing as t
+import warnings
from collections import abc
from collections import deque
from random import choice
from markupsafe import escape
from markupsafe import Markup
+if t.TYPE_CHECKING:
+ F = t.TypeVar("F", bound=t.Callable[..., t.Any])
+
# special singleton representing missing values for the runtime
missing = type("MissingType", (), {"__repr__": lambda x: "missing"})()
_slash_escape = "\\/" not in json.dumps("/")
-def contextfunction(f):
- """This decorator can be used to mark a function or method context callable.
- A context callable is passed the active :class:`Context` as first argument when
- called from the template. This is useful if a function wants to get access
- to the context or functions provided on the context object. For example
- a function that returns a sorted list of template variables the current
- template exports could look like this::
-
- @contextfunction
- def get_exported_names(context):
- return sorted(context.exported_vars)
+def pass_context(f: "F") -> "F":
+ """Pass the :class:`~jinja2.runtime.Context` as the first argument
+ to the decorated function when called while rendering a template.
+
+ Can be used on functions, filters, and tests.
+
+ If only ``Context.eval_context`` is needed, use
+ :func:`pass_eval_context`. If only ``Context.environment`` is
+ needed, use :func:`pass_environment`.
+
+ .. versionadded:: 3.0.0
+ Replaces ``contextfunction`` and ``contextfilter``.
+ """
+ f.jinja_pass_arg = _PassArg.context # type: ignore
+ return f
+
+
+def pass_eval_context(f: "F") -> "F":
+ """Pass the :class:`~jinja2.nodes.EvalContext` as the first argument
+ to the decorated function when called while rendering a template.
+ See :ref:`eval-context`.
+
+ Can be used on functions, filters, and tests.
+
+ If only ``EvalContext.environment`` is needed, use
+ :func:`pass_environment`.
+
+ .. versionadded:: 3.0.0
+ Replaces ``evalcontextfunction`` and ``evalcontextfilter``.
"""
- f.contextfunction = True
+ f.jinja_pass_arg = _PassArg.eval_context # type: ignore
return f
+def pass_environment(f: "F") -> "F":
+ """Pass the :class:`~jinja2.Environment` as the first argument to
+ the decorated function when called while rendering a template.
+
+ Can be used on functions, filters, and tests.
+
+ .. versionadded:: 3.0.0
+ Replaces ``environmentfunction`` and ``environmentfilter``.
+ """
+ f.jinja_pass_arg = _PassArg.environment # type: ignore
+ return f
+
+
+class _PassArg(enum.Enum):
+ context = enum.auto()
+ eval_context = enum.auto()
+ environment = enum.auto()
+
+ @classmethod
+ def from_obj(cls, obj):
+ if hasattr(obj, "jinja_pass_arg"):
+ return obj.jinja_pass_arg
+
+ for prefix in "context", "eval_context", "environment":
+ squashed = prefix.replace("_", "")
+
+ for name in f"{squashed}function", f"{squashed}filter":
+ if getattr(obj, name, False) is True:
+ warnings.warn(
+ f"{name!r} is deprecated and will stop working"
+ f" in Jinja 3.1. Use 'pass_{prefix}' instead.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ return cls[prefix]
+
+
+def contextfunction(f):
+ """Pass the context as the first argument to the decorated function.
+
+ .. deprecated:: 3.0.0
+ Use :func:`~jinja2.pass_context` instead.
+ """
+ warnings.warn(
+ "'contextfunction' is renamed to 'pass_context', the old name"
+ " will be removed in Jinja 3.1.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ return pass_context(f)
+
+
def evalcontextfunction(f):
- """This decorator can be used to mark a function or method as an eval
- context callable. This is similar to the :func:`contextfunction`
- but instead of passing the context, an evaluation context object is
- passed. For more information about the eval context, see
- :ref:`eval-context`.
+ """Pass the eval context as the first argument to the decorated
+ function.
+
+ .. deprecated:: 3.0.0
+ Use :func:`~jinja2.pass_eval_context` instead.
.. versionadded:: 2.4
"""
- f.evalcontextfunction = True
- return f
+ warnings.warn(
+ "'evalcontextfunction' is renamed to 'pass_eval_context', the"
+ " old name will be removed in Jinja 3.1.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ return pass_eval_context(f)
def environmentfunction(f):
- """This decorator can be used to mark a function or method as environment
- callable. This decorator works exactly like the :func:`contextfunction`
- decorator just that the first argument is the active :class:`Environment`
- and not context.
+ """Pass the environment as the first argument to the decorated
+ function.
+
+ .. deprecated:: 3.0.0
+ Use :func:`~jinja2.pass_environment` instead.
"""
- f.environmentfunction = True
- return f
+ warnings.warn(
+ "'environmentfunction' is renamed to 'pass_environment', the"
+ " old name will be removed in Jinja 3.1.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ return pass_environment(f)
def internalcode(f):
from jinja2 import UndefinedError
from jinja2.compiler import CodeGenerator
from jinja2.runtime import Context
-from jinja2.utils import contextfunction
from jinja2.utils import Cycler
-from jinja2.utils import environmentfunction
-from jinja2.utils import evalcontextfunction
+from jinja2.utils import pass_context
+from jinja2.utils import pass_environment
+from jinja2.utils import pass_eval_context
class TestExtendedAPI:
assert t.render(value=123) == "<int>"
def test_context_finalize(self):
- @contextfunction
+ @pass_context
def finalize(context, value):
return value * context["scale"]
assert t.render(value=5, scale=3) == "15"
def test_eval_finalize(self):
- @evalcontextfunction
+ @pass_eval_context
def finalize(eval_ctx, value):
return str(eval_ctx.autoescape) + value
assert t.render(value="<script>") == "True<script>"
def test_env_autoescape(self):
- @environmentfunction
+ @pass_environment
def finalize(env, value):
return " ".join(
(env.variable_start_string, repr(value), env.variable_end_string)
import pytest
-from jinja2 import contextfunction
from jinja2 import DictLoader
from jinja2 import Environment
from jinja2 import nodes
+from jinja2 import pass_context
from jinja2.exceptions import TemplateAssertionError
from jinja2.ext import Extension
from jinja2.lexer import count_newlines
return value
-@contextfunction
+@pass_context
def gettext(context, string):
language = context.get("LANGUAGE", "en")
value = languages.get(language, {}).get(string, string)
return _get_with_context(value)
-@contextfunction
+@pass_context
def ngettext(context, s, p, n):
language = context.get("LANGUAGE", "en")
return _get_with_context(value)
-@contextfunction
+@pass_context
def pgettext(context, c, s):
language = context.get("LANGUAGE", "en")
value = languages.get(language, {}).get(s, s)
return _get_with_context(value, c)
-@contextfunction
+@pass_context
def npgettext(context, c, s, p, n):
language = context.get("LANGUAGE", "en")
from jinja2 import TemplateAssertionError
from jinja2 import TemplateNotFound
from jinja2 import TemplateSyntaxError
-from jinja2.utils import contextfunction
+from jinja2.utils import pass_context
class TestCorner:
assert e.value.name == "foo/bar.html"
- def test_contextfunction_callable_classes(self, env):
- from jinja2.utils import contextfunction
-
+ def test_pass_context_callable_class(self, env):
class CallableClass:
- @contextfunction
+ @pass_context
def __call__(self, ctx):
return ctx.resolve("hello")
)
assert tmpl.render() == "Start\n1) foo\n2) bar last\nEnd"
- def test_contextfunction_loop_vars(self, env):
- @contextfunction
+ def test_pass_context_loop_vars(self, env):
+ @pass_context
def test(ctx):
return f"{ctx['i']}{ctx['j']}"
tmpl.globals["test"] = test
assert tmpl.render() == "42\n01\n01\n42\n12\n12\n42"
- def test_contextfunction_scoped_loop_vars(self, env):
- @contextfunction
+ def test_pass_context_scoped_loop_vars(self, env):
+ @pass_context
def test(ctx):
return f"{ctx['i']}"
tmpl.globals["test"] = test
assert tmpl.render() == "42\n0\n42\n1\n42"
- def test_contextfunction_in_blocks(self, env):
- @contextfunction
+ def test_pass_context_in_blocks(self, env):
+ @pass_context
def test(ctx):
return f"{ctx['i']}"
tmpl.globals["test"] = test
assert tmpl.render() == "42\n24\n42"
- def test_contextfunction_block_and_loop(self, env):
- @contextfunction
+ def test_pass_context_block_and_loop(self, env):
+ @pass_context
def test(ctx):
return f"{ctx['i']}"
assert out == "1 [(1, 'a'), (1, 'b')]\n2 [(2, 'c')]\n3 [(3, 'd')]\n"
-def test_mock_not_contextfunction():
+def test_mock_not_pass_arg_marker():
"""If a callable class has a ``__getattr__`` that returns True-like
values for arbitrary attrs, it should not be incorrectly identified
- as a ``contextfunction``.
+ as a ``pass_context`` function.
"""
class Calc:
projects / thirdparty / jinja.git / commitdiff
