diff options
author | David Lord <davidism@gmail.com> | 2021-02-01 22:48:29 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-02-01 22:48:29 -0800 |
commit | f009a004a2e70a3608d49aceb1814b90bb4370d6 (patch) | |
tree | c6979fc0658352f02465864e56b8d51fe9b5cc7d | |
parent | fcf014f80ca3032f6db19bbbcf847ee44ad8a85e (diff) | |
parent | f2fdf1861078b06080997c89cd9589ebfdc73c25 (diff) | |
download | jinja2-f009a004a2e70a3608d49aceb1814b90bb4370d6.tar.gz |
Merge pull request #1348 from pallets/json-docs
update tojson docs
-rw-r--r-- | src/jinja2/filters.py | 40 | ||||
-rw-r--r-- | src/jinja2/utils.py | 52 |
2 files changed, 46 insertions, 46 deletions
diff --git a/src/jinja2/filters.py b/src/jinja2/filters.py index db80aa5..9fb52ed 100644 --- a/src/jinja2/filters.py +++ b/src/jinja2/filters.py @@ -1251,37 +1251,29 @@ def do_rejectattr(*args, **kwargs): @evalcontextfilter def do_tojson(eval_ctx, value, indent=None): - """Dumps a structure to JSON so that it's safe to use in ``<script>`` - tags. It accepts the same arguments and returns a JSON string. Note that - this is available in templates through the ``|tojson`` filter which will - also mark the result as safe. Due to how this function escapes certain - characters this is safe even if used outside of ``<script>`` tags. + """Serialize an object to a string of JSON, and mark it safe to + render in HTML. This filter is only for use in HTML documents. - The following characters are escaped in strings: + The returned string is safe to render in HTML documents and + ``<script>`` tags. The exception is in HTML attributes that are + double quoted; either use single quotes or the ``|forceescape`` + filter. - - ``<`` - - ``>`` - - ``&`` - - ``'`` - - This makes it safe to embed such strings in any place in HTML with the - notable exception of double quoted attributes. In that case single - quote your attributes or HTML escape it in addition. - - The indent parameter can be used to enable pretty printing. Set it to - the number of spaces that the structures should be indented with. - - Note that this filter is for use in HTML contexts only. + :param value: The object to serialize to JSON. + :param indent: The ``indent`` parameter passed to ``dumps``, for + pretty-printing the value. .. versionadded:: 2.9 """ policies = eval_ctx.environment.policies - dumper = policies["json.dumps_function"] - options = policies["json.dumps_kwargs"] + dumps = policies["json.dumps_function"] + kwargs = policies["json.dumps_kwargs"] + if indent is not None: - options = dict(options) - options["indent"] = indent - return htmlsafe_json_dumps(value, dumper=dumper, **options) + kwargs = kwargs.copy() + kwargs["indent"] = indent + + return htmlsafe_json_dumps(value, dumps=dumps, **kwargs) def prepare_map(args, kwargs): diff --git a/src/jinja2/utils.py b/src/jinja2/utils.py index 18e6d1a..289d27c 100644 --- a/src/jinja2/utils.py +++ b/src/jinja2/utils.py @@ -608,34 +608,42 @@ def select_autoescape( return autoescape -def htmlsafe_json_dumps(obj, dumper=None, **kwargs): - """Works exactly like :func:`dumps` but is safe for use in ``<script>`` - tags. It accepts the same arguments and returns a JSON string. Note that - this is available in templates through the ``|tojson`` filter which will - also mark the result as safe. Due to how this function escapes certain - characters this is safe even if used outside of ``<script>`` tags. - - The following characters are escaped in strings: - - - ``<`` - - ``>`` - - ``&`` - - ``'`` - - This makes it safe to embed such strings in any place in HTML with the - notable exception of double quoted attributes. In that case single - quote your attributes or HTML escape it in addition. +def htmlsafe_json_dumps(obj, dumps=None, **kwargs): + """Serialize an object to a string of JSON with :func:`json.dumps`, + then replace HTML-unsafe characters with Unicode escapes and mark + the result safe with :class:`~markupsafe.Markup`. + + This is available in templates as the ``|tojson`` filter. + + The following characters are escaped: ``<``, ``>``, ``&``, ``'``. + + The returned string is safe to render in HTML documents and + ``<script>`` tags. The exception is in HTML attributes that are + double quoted; either use single quotes or the ``|forceescape`` + filter. + + :param obj: The object to serialize to JSON. + :param dumps: The ``dumps`` function to use. Defaults to + ``env.policies["json.dumps_function"]``, which defaults to + :func:`json.dumps`. + :param kwargs: Extra arguments to pass to ``dumps``. Merged onto + ``env.policies["json.dumps_kwargs"]``. + + .. versionchanged:: 3.0 + The ``dumper`` parameter is renamed to ``dumps``. + + .. versionadded:: 2.9 """ - if dumper is None: - dumper = json.dumps - rv = ( - dumper(obj, **kwargs) + if dumps is None: + dumps = json.dumps + + return Markup( + dumps(obj, **kwargs) .replace("<", "\\u003c") .replace(">", "\\u003e") .replace("&", "\\u0026") .replace("'", "\\u0027") ) - return Markup(rv) class Cycler: |