Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/flask/json/__init__.py: 40%

1from __future__ import annotations 

2 

3import json as _json 

4import typing as t 

5 

6from ..globals import current_app 

7from .provider import _default 

8 

9if t.TYPE_CHECKING: # pragma: no cover 

10 from ..wrappers import Response 

11 

12 

13def 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 

47def 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 

77def 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 

108def 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 

138def 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) # type: ignore[return-value]