venv/lib/python3.11/site-packages/flask/json/__init__.py

   1 from __future__ import annotations
   2
   3 import json as _json
   4 import typing as t
   5
   6 from ..globals import current_app
   7 from .provider import _default
   8
   9 if t.TYPE_CHECKING:  # pragma: no cover
  10     from ..wrappers import Response
  11
  12
  13 def dumps(obj: t.Any, **kwargs: t.Any) -> str:
  14     """Serialize data as JSON.
  15
  16     If :data:`~flask.current_app` is available, it will use its
  17     :meth:`app.json.dumps() <flask.json.provider.JSONProvider.dumps>`
  18     method, otherwise it will use :func:`json.dumps`.
  19
  20     :param obj: The data to serialize.
  21     :param kwargs: Arguments passed to the ``dumps`` implementation.
  22
  23     .. versionchanged:: 2.3
  24         The ``app`` parameter was removed.
  25
  26     .. versionchanged:: 2.2
  27         Calls ``current_app.json.dumps``, allowing an app to override
  28         the behavior.
  29
  30     .. versionchanged:: 2.0.2
  31         :class:`decimal.Decimal` is supported by converting to a string.
  32
  33     .. versionchanged:: 2.0
  34         ``encoding`` will be removed in Flask 2.1.
  35
  36     .. versionchanged:: 1.0.3
  37         ``app`` can be passed directly, rather than requiring an app
  38         context for configuration.
  39     """
  40     if current_app:
  41         return current_app.json.dumps(obj, **kwargs)
  42
  43     kwargs.setdefault("default", _default)
  44     return _json.dumps(obj, **kwargs)
  45
  46
  47 def dump(obj: t.Any, fp: t.IO[str], **kwargs: t.Any) -> None:
  48     """Serialize data as JSON and write to a file.
  49
  50     If :data:`~flask.current_app` is available, it will use its
  51     :meth:`app.json.dump() <flask.json.provider.JSONProvider.dump>`
  52     method, otherwise it will use :func:`json.dump`.
  53
  54     :param obj: The data to serialize.
  55     :param fp: A file opened for writing text. Should use the UTF-8
  56         encoding to be valid JSON.
  57     :param kwargs: Arguments passed to the ``dump`` implementation.
  58
  59     .. versionchanged:: 2.3
  60         The ``app`` parameter was removed.
  61
  62     .. versionchanged:: 2.2
  63         Calls ``current_app.json.dump``, allowing an app to override
  64         the behavior.
  65
  66     .. versionchanged:: 2.0
  67         Writing to a binary file, and the ``encoding`` argument, will be
  68         removed in Flask 2.1.
  69     """
  70     if current_app:
  71         current_app.json.dump(obj, fp, **kwargs)
  72     else:
  73         kwargs.setdefault("default", _default)
  74         _json.dump(obj, fp, **kwargs)
  75
  76
  77 def loads(s: str | bytes, **kwargs: t.Any) -> t.Any:
  78     """Deserialize data as JSON.
  79
  80     If :data:`~flask.current_app` is available, it will use its
  81     :meth:`app.json.loads() <flask.json.provider.JSONProvider.loads>`
  82     method, otherwise it will use :func:`json.loads`.
  83
  84     :param s: Text or UTF-8 bytes.
  85     :param kwargs: Arguments passed to the ``loads`` implementation.
  86
  87     .. versionchanged:: 2.3
  88         The ``app`` parameter was removed.
  89
  90     .. versionchanged:: 2.2
  91         Calls ``current_app.json.loads``, allowing an app to override
  92         the behavior.
  93
  94     .. versionchanged:: 2.0
  95         ``encoding`` will be removed in Flask 2.1. The data must be a
  96         string or UTF-8 bytes.
  97
  98     .. versionchanged:: 1.0.3
  99         ``app`` can be passed directly, rather than requiring an app
 100         context for configuration.
 101     """
 102     if current_app:
 103         return current_app.json.loads(s, **kwargs)
 104
 105     return _json.loads(s, **kwargs)
 106
 107
 108 def load(fp: t.IO[t.AnyStr], **kwargs: t.Any) -> t.Any:
 109     """Deserialize data as JSON read from a file.
 110
 111     If :data:`~flask.current_app` is available, it will use its
 112     :meth:`app.json.load() <flask.json.provider.JSONProvider.load>`
 113     method, otherwise it will use :func:`json.load`.
 114
 115     :param fp: A file opened for reading text or UTF-8 bytes.
 116     :param kwargs: Arguments passed to the ``load`` implementation.
 117
 118     .. versionchanged:: 2.3
 119         The ``app`` parameter was removed.
 120
 121     .. versionchanged:: 2.2
 122         Calls ``current_app.json.load``, allowing an app to override
 123         the behavior.
 124
 125     .. versionchanged:: 2.2
 126         The ``app`` parameter will be removed in Flask 2.3.
 127
 128     .. versionchanged:: 2.0
 129         ``encoding`` will be removed in Flask 2.1. The file must be text
 130         mode, or binary mode with UTF-8 bytes.
 131     """
 132     if current_app:
 133         return current_app.json.load(fp, **kwargs)
 134
 135     return _json.load(fp, **kwargs)
 136
 137
 138 def jsonify(*args: t.Any, **kwargs: t.Any) -> Response:
 139     """Serialize the given arguments as JSON, and return a
 140     :class:`~flask.Response` object with the ``application/json``
 141     mimetype. A dict or list returned from a view will be converted to a
 142     JSON response automatically without needing to call this.
 143
 144     This requires an active request or application context, and calls
 145     :meth:`app.json.response() <flask.json.provider.JSONProvider.response>`.
 146
 147     In debug mode, the output is formatted with indentation to make it
 148     easier to read. This may also be controlled by the provider.
 149
 150     Either positional or keyword arguments can be given, not both.
 151     If no arguments are given, ``None`` is serialized.
 152
 153     :param args: A single value to serialize, or multiple values to
 154         treat as a list to serialize.
 155     :param kwargs: Treat as a dict to serialize.
 156
 157     .. versionchanged:: 2.2
 158         Calls ``current_app.json.response``, allowing an app to override
 159         the behavior.
 160
 161     .. versionchanged:: 2.0.2
 162         :class:`decimal.Decimal` is supported by converting to a string.
 163
 164     .. versionchanged:: 0.11
 165         Added support for serializing top-level arrays. This was a
 166         security risk in ancient browsers. See :ref:`security-json`.
 167
 168     .. versionadded:: 0.2
 169     """
 170     return current_app.json.response(*args, **kwargs)