From: David Lord <davidism@gmail.com>
Date: Tue, 2 Feb 2021 06:35:43 +0000 (-0800)
Subject: update tojson docs
X-Git-Tag: 3.0.0rc1~38^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F1348%2Fhead;p=thirdparty%2Fjinja.git

update tojson docs
---

diff --git a/src/jinja2/filters.py b/src/jinja2/filters.py
index db80aa5a..9fb52ed4 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 18e6d1ab..289d27c6 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: