from __future__ import annotations
import json as _json
import typing as t
from . . globals import current_app
from . provider import _default
if t . TYPE_CHECKING : # pragma: no cover
from . . wrappers import Response
def dumps ( obj : t . Any , * * kwargs : t . Any ) - > str :
""" Serialize data as JSON.
If : data : ` ~ flask . current_app ` is available , it will use its
: meth : ` app . json . dumps ( ) < flask . json . provider . JSONProvider . dumps > `
method , otherwise it will use : func : ` json . dumps ` .
: param obj : The data to serialize .
: param kwargs : Arguments passed to the ` ` dumps ` ` implementation .
. . versionchanged : : 2.3
The ` ` app ` ` parameter was removed .
. . versionchanged : : 2.2
Calls ` ` current_app . json . dumps ` ` , allowing an app to override
the behavior .
. . versionchanged : : 2.0 .2
: class : ` decimal . Decimal ` is supported by converting to a string .
. . versionchanged : : 2.0
` ` encoding ` ` will be removed in Flask 2.1 .
. . versionchanged : : 1.0 .3
` ` app ` ` can be passed directly , rather than requiring an app
context for configuration .
"""
if current_app :
return current_app . json . dumps ( obj , * * kwargs )
kwargs . setdefault ( " default " , _default )
return _json . dumps ( obj , * * kwargs )
def dump ( obj : t . Any , fp : t . IO [ str ] , * * kwargs : t . Any ) - > None :
""" Serialize data as JSON and write to a file.
If : data : ` ~ flask . current_app ` is available , it will use its
: meth : ` app . json . dump ( ) < flask . json . provider . JSONProvider . dump > `
method , otherwise it will use : func : ` json . dump ` .
: param obj : The data to serialize .
: param fp : A file opened for writing text . Should use the UTF - 8
encoding to be valid JSON .
: param kwargs : Arguments passed to the ` ` dump ` ` implementation .
. . versionchanged : : 2.3
The ` ` app ` ` parameter was removed .
. . versionchanged : : 2.2
Calls ` ` current_app . json . dump ` ` , allowing an app to override
the behavior .
. . versionchanged : : 2.0
Writing to a binary file , and the ` ` encoding ` ` argument , will be
removed in Flask 2.1 .
"""
if current_app :
current_app . json . dump ( obj , fp , * * kwargs )
else :
kwargs . setdefault ( " default " , _default )
_json . dump ( obj , fp , * * kwargs )
def loads ( s : str | bytes , * * kwargs : t . Any ) - > t . Any :
""" Deserialize data as JSON.
If : data : ` ~ flask . current_app ` is available , it will use its
: meth : ` app . json . loads ( ) < flask . json . provider . JSONProvider . loads > `
method , otherwise it will use : func : ` json . loads ` .
: param s : Text or UTF - 8 bytes .
: param kwargs : Arguments passed to the ` ` loads ` ` implementation .
. . versionchanged : : 2.3
The ` ` app ` ` parameter was removed .
. . versionchanged : : 2.2
Calls ` ` current_app . json . loads ` ` , allowing an app to override
the behavior .
. . versionchanged : : 2.0
` ` encoding ` ` will be removed in Flask 2.1 . The data must be a
string or UTF - 8 bytes .
. . versionchanged : : 1.0 .3
` ` app ` ` can be passed directly , rather than requiring an app
context for configuration .
"""
if current_app :
return current_app . json . loads ( s , * * kwargs )
return _json . loads ( s , * * kwargs )
def load ( fp : t . IO [ t . AnyStr ] , * * kwargs : t . Any ) - > t . Any :
""" Deserialize data as JSON read from a file.
If : data : ` ~ flask . current_app ` is available , it will use its
: meth : ` app . json . load ( ) < flask . json . provider . JSONProvider . load > `
method , otherwise it will use : func : ` json . load ` .
: param fp : A file opened for reading text or UTF - 8 bytes .
: param kwargs : Arguments passed to the ` ` load ` ` implementation .
. . versionchanged : : 2.3
The ` ` app ` ` parameter was removed .
. . versionchanged : : 2.2
Calls ` ` current_app . json . load ` ` , allowing an app to override
the behavior .
. . versionchanged : : 2.2
The ` ` app ` ` parameter will be removed in Flask 2.3 .
. . versionchanged : : 2.0
` ` encoding ` ` will be removed in Flask 2.1 . The file must be text
mode , or binary mode with UTF - 8 bytes .
"""
if current_app :
return current_app . json . load ( fp , * * kwargs )
return _json . load ( fp , * * kwargs )
def jsonify ( * args : t . Any , * * kwargs : t . Any ) - > Response :
""" Serialize the given arguments as JSON, and return a
: class : ` ~ flask . Response ` object with the ` ` application / json ` `
mimetype . A dict or list returned from a view will be converted to a
JSON response automatically without needing to call this .
This requires an active request or application context , and calls
: meth : ` app . json . response ( ) < flask . json . provider . JSONProvider . response > ` .
In debug mode , the output is formatted with indentation to make it
easier to read . This may also be controlled by the provider .
Either positional or keyword arguments can be given , not both .
If no arguments are given , ` ` None ` ` is serialized .
: param args : A single value to serialize , or multiple values to
treat as a list to serialize .
: param kwargs : Treat as a dict to serialize .
. . versionchanged : : 2.2
Calls ` ` current_app . json . response ` ` , allowing an app to override
the behavior .
. . versionchanged : : 2.0 .2
: class : ` decimal . Decimal ` is supported by converting to a string .
. . versionchanged : : 0.11
Added support for serializing top - level arrays . This was a
security risk in ancient browsers . See : ref : ` security - json ` .
. . versionadded : : 0.2
"""
return current_app . json . response ( * args , * * kwargs ) # type: ignore[return-value]