# flask.json package

## Submodules

## flask.json.provider module

class flask.json.provider.DefaultJSONProvider(app: App)

  Bases: `JSONProvider`

  Provide JSON operations using Python’s built-in `json` library. Serializes the following additional data types:

  - `datetime.datetime` and `datetime.date` are serialized to RFC 822 strings. This is the same as the HTTP date format.

  - `uuid.UUID` is serialized to a string.

  - `dataclasses.dataclass` is passed to `dataclasses.asdict()`.

  - `Markup` (or any object with a `__html__` method) will call the `__html__` method to get a string.

  compact: bool | None = None

    If `True`, or `None` out of debug mode, the `response()` output will not add indentation, newlines, or spaces. If `False`, or `None` in debug mode, it will use a non-compact representation.

  static default(o: Any) → Any

    Apply this function to any object that `json.dumps()` does not know how to serialize. It should return a valid JSON type or raise a `TypeError`.

  dumps(obj: Any, **kwargs: Any) → str

    Serialize data as JSON to a string.

    Keyword arguments are passed to `json.dumps()`. Sets some parameter defaults from the `default`, `ensure_ascii`, and `sort_keys` attributes.

    Parameters:

      - obj – The data to serialize.

      - kwargs – Passed to `json.dumps()`.

  ensure_ascii = True

    Replace non-ASCII characters with escape sequences. This may be more compatible with some clients, but can be disabled for better performance and size.

  loads(s: str | bytes, **kwargs: Any) → Any

    Deserialize data as JSON from a string or bytes.

    Parameters:

      - s – Text or UTF-8 bytes.

      - kwargs – Passed to `json.loads()`.

  mimetype = 'application/json'

    The mimetype set in `response()`.

  response(*args: t.Any, **kwargs: t.Any) → Response

    Serialize the given arguments as JSON, and return a `Response` object with it. The response mimetype will be “application/json” and can be changed with `mimetype`.

    If `compact` is `False` or debug mode is enabled, the output will be formatted to be easier to read.

    Either positional or keyword arguments can be given, not both. If no arguments are given, `None` is serialized.

    Parameters:

      - args – A single value to serialize, or multiple values to treat as a list to serialize.

      - kwargs – Treat as a dict to serialize.

  sort_keys = True

    Sort the keys in any serialized dicts. This may be useful for some caching situations, but can be disabled for better performance. When enabled, keys must all be strings, they are not converted before sorting.

class flask.json.provider.JSONProvider(app: App)

  Bases: `object`

  A standard set of JSON operations for an application. Subclasses of this can be used to customize JSON behavior or use different JSON libraries.

  To implement a provider for a specific library, subclass this base class and implement at least `dumps()` and `loads()`. All other methods have default implementations.

  To use a different provider, either subclass `Flask` and set `json_provider_class` to a provider class, or set `app.json` to an instance of the class.

  Parameters:

    app – An application instance. This will be stored as a `weakref.proxy` on the `_app` attribute.

  Added in version 2.2.

  dump(obj: Any, fp: IO[str], **kwargs: Any) → None

    Serialize data as JSON and write to a file.

    Parameters:

      - obj – The data to serialize.

      - fp – A file opened for writing text. Should use the UTF-8 encoding to be valid JSON.

      - kwargs – May be passed to the underlying JSON library.

  dumps(obj: Any, **kwargs: Any) → str

    Serialize data as JSON.

    Parameters:

      - obj – The data to serialize.

      - kwargs – May be passed to the underlying JSON library.

  load(fp: IO, **kwargs: Any) → Any

    Deserialize data as JSON read from a file.

    Parameters:

      - fp – A file opened for reading text or UTF-8 bytes.

      - kwargs – May be passed to the underlying JSON library.

  loads(s: str | bytes, **kwargs: Any) → Any

    Deserialize data as JSON.

    Parameters:

      - s – Text or UTF-8 bytes.

      - kwargs – May be passed to the underlying JSON library.

  response(*args: t.Any, **kwargs: t.Any) → Response

    Serialize the given arguments as JSON, and return a `Response` object with the `application/json` mimetype.

    The `jsonify()` function calls this method for the current application.

    Either positional or keyword arguments can be given, not both. If no arguments are given, `None` is serialized.

    Parameters:

      - args – A single value to serialize, or multiple values to treat as a list to serialize.

      - kwargs – Treat as a dict to serialize.

## flask.json.tag module

### Tagged JSON

A compact representation for lossless serialization of non-standard JSON types. `SecureCookieSessionInterface` uses this to serialize the session data, but it may be useful in other places. It can be extended to support other types.

class flask.json.tag.TaggedJSONSerializer

  Serializer that uses a tag system to compactly represent objects that are not JSON types. Passed as the intermediate serializer to `itsdangerous.Serializer`.

  The following extra types are supported:

  - `dict`

  - `tuple`

  - `bytes`

  - `Markup`

  - `UUID`

  - `datetime`

  default_tags = [<class 'flask.json.tag.TagDict'>, <class 'flask.json.tag.PassDict'>, <class 'flask.json.tag.TagTuple'>, <class 'flask.json.tag.PassList'>, <class 'flask.json.tag.TagBytes'>, <class 'flask.json.tag.TagMarkup'>, <class 'flask.json.tag.TagUUID'>, <class 'flask.json.tag.TagDateTime'>]

    Tag classes to bind when creating the serializer. Other tags can be added later using `register()`.

  dumps(value: Any) → str

    Tag the value and dump it to a compact JSON string.

  loads(value: str) → Any

    Load data from a JSON string and deserialized any tagged objects.

  register(tag_class: type[JSONTag], force: bool = False, index: int | None = None) → None

    Register a new tag with this serializer.

    Parameters:

      - tag_class – tag class to register. Will be instantiated with this serializer instance.

      - force – overwrite an existing tag. If false (default), a `KeyError` is raised.

      - index – index to insert the new tag in the tag order. Useful when the new tag is a special case of an existing tag. If `None` (default), the tag is appended to the end of the order.

    Raises:

      KeyError – if the tag key is already registered and `force` is not true.

  tag(value: Any) → Any

    Convert a value to a tagged representation if necessary.

  untag(value: dict[str, Any]) → Any

    Convert a tagged representation back to the original type.

class flask.json.tag.JSONTag(serializer: TaggedJSONSerializer)

  Base class for defining type tags for `TaggedJSONSerializer`.

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  key: str = ''

    The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

  tag(value: Any) → dict[str, Any]

    Convert the value to a valid JSON type and add the tag structure around it.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

  to_python(value: Any) → Any

    Convert the JSON representation back to the correct type. The tag will already be removed.

Let’s see an example that adds support for `OrderedDict`. Dicts don’t have an order in JSON, so to handle this we will dump the items as a list of `[key, value]` pairs. Subclass `JSONTag` and give it the new key `' od'` to identify the type. The session serializer processes dicts first, so insert the new tag at the front of the order since `OrderedDict` must be processed before `dict`.

    from flask.json.tag import JSONTag

    class TagOrderedDict(JSONTag):
        __slots__ = ('serializer',)
        key = ' od'

        def check(self, value):
            return isinstance(value, OrderedDict)

        def to_json(self, value):
            return [[k, self.serializer.tag(v)] for k, v in iteritems(value)]

        def to_python(self, value):
            return OrderedDict(value)

    app.session_interface.serializer.register(TagOrderedDict, index=0)

class flask.json.tag.JSONTag(serializer: TaggedJSONSerializer)

  Bases: `object`

  Base class for defining type tags for `TaggedJSONSerializer`.

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  key: str = ''

    The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

  serializer
  tag(value: Any) → dict[str, Any]

    Convert the value to a valid JSON type and add the tag structure around it.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

  to_python(value: Any) → Any

    Convert the JSON representation back to the correct type. The tag will already be removed.

class flask.json.tag.PassDict(serializer: TaggedJSONSerializer)

  Bases: `JSONTag`

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  tag(value: Any) → Any

    Convert the value to a valid JSON type and add the tag structure around it.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

class flask.json.tag.PassList(serializer: TaggedJSONSerializer)

  Bases: `JSONTag`

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  tag(value: Any) → Any

    Convert the value to a valid JSON type and add the tag structure around it.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

class flask.json.tag.TagBytes(serializer: TaggedJSONSerializer)

  Bases: `JSONTag`

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  key: str = ' b'

    The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

  to_python(value: Any) → Any

    Convert the JSON representation back to the correct type. The tag will already be removed.

class flask.json.tag.TagDateTime(serializer: TaggedJSONSerializer)

  Bases: `JSONTag`

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  key: str = ' d'

    The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

  to_python(value: Any) → Any

    Convert the JSON representation back to the correct type. The tag will already be removed.

class flask.json.tag.TagDict(serializer: TaggedJSONSerializer)

  Bases: `JSONTag`

  Tag for 1-item dicts whose only key matches a registered tag.

  Internally, the dict key is suffixed with __, and the suffix is removed when deserializing.

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  key: str = ' di'

    The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

  to_python(value: Any) → Any

    Convert the JSON representation back to the correct type. The tag will already be removed.

class flask.json.tag.TagMarkup(serializer: TaggedJSONSerializer)

  Bases: `JSONTag`

  Serialize anything matching the `Markup` API by having a `__html__` method to the result of that method. Always deserializes to an instance of `Markup`.

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  key: str = ' m'

    The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

  to_python(value: Any) → Any

    Convert the JSON representation back to the correct type. The tag will already be removed.

class flask.json.tag.TagTuple(serializer: TaggedJSONSerializer)

  Bases: `JSONTag`

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  key: str = ' t'

    The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

  to_python(value: Any) → Any

    Convert the JSON representation back to the correct type. The tag will already be removed.

class flask.json.tag.TagUUID(serializer: TaggedJSONSerializer)

  Bases: `JSONTag`

  check(value: Any) → bool

    Check if the given value should be tagged by this tag.

  key: str = ' u'

    The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

  to_json(value: Any) → Any

    Convert the Python object to an object that is a valid JSON type. The tag will be added later.

  to_python(value: Any) → Any

    Convert the JSON representation back to the correct type. The tag will already be removed.

class flask.json.tag.TaggedJSONSerializer

  Bases: `object`

  Serializer that uses a tag system to compactly represent objects that are not JSON types. Passed as the intermediate serializer to `itsdangerous.Serializer`.

  The following extra types are supported:

  - `dict`

  - `tuple`

  - `bytes`

  - `Markup`

  - `UUID`

  - `datetime`

  default_tags = [<class 'flask.json.tag.TagDict'>, <class 'flask.json.tag.PassDict'>, <class 'flask.json.tag.TagTuple'>, <class 'flask.json.tag.PassList'>, <class 'flask.json.tag.TagBytes'>, <class 'flask.json.tag.TagMarkup'>, <class 'flask.json.tag.TagUUID'>, <class 'flask.json.tag.TagDateTime'>]

    Tag classes to bind when creating the serializer. Other tags can be added later using `register()`.

  dumps(value: Any) → str

    Tag the value and dump it to a compact JSON string.

  loads(value: str) → Any

    Load data from a JSON string and deserialized any tagged objects.

  order: list[JSONTag]
  register(tag_class: type[JSONTag], force: bool = False, index: int | None = None) → None

    Register a new tag with this serializer.

    Parameters:

      - tag_class – tag class to register. Will be instantiated with this serializer instance.

      - force – overwrite an existing tag. If false (default), a `KeyError` is raised.

      - index – index to insert the new tag in the tag order. Useful when the new tag is a special case of an existing tag. If `None` (default), the tag is appended to the end of the order.

    Raises:

      KeyError – if the tag key is already registered and `force` is not true.

  tag(value: Any) → Any

    Convert a value to a tagged representation if necessary.

  tags: dict[str, JSONTag]
  untag(value: dict[str, Any]) → Any

    Convert a tagged representation back to the original type.

## Module contents

flask.json.dump(obj: Any, fp: IO[str], **kwargs: Any) → None

  Serialize data as JSON and write to a file.

  If `current_app` is available, it will use its `app.json.dump()` method, otherwise it will use `json.dump()`.

  Parameters:

    - obj – The data to serialize.

    - fp – A file opened for writing text. Should use the UTF-8 encoding to be valid JSON.

    - kwargs – Arguments passed to the `dump` implementation.

  Changed in version 2.3: The `app` parameter was removed.

  Changed in version 2.2: Calls `current_app.json.dump`, allowing an app to override the behavior.

  Changed in version 2.0: Writing to a binary file, and the `encoding` argument, will be removed in Flask 2.1.

flask.json.dumps(obj: Any, **kwargs: Any) → str

  Serialize data as JSON.

  If `current_app` is available, it will use its `app.json.dumps()` method, otherwise it will use `json.dumps()`.

  Parameters:

    - obj – The data to serialize.

    - kwargs – Arguments passed to the `dumps` implementation.

  Changed in version 2.3: The `app` parameter was removed.

  Changed in version 2.2: Calls `current_app.json.dumps`, allowing an app to override the behavior.

  Changed in version 2.0.2: `decimal.Decimal` is supported by converting to a string.

  Changed in version 2.0: `encoding` will be removed in Flask 2.1.

  Changed in version 1.0.3: `app` can be passed directly, rather than requiring an app context for configuration.

flask.json.jsonify(*args: t.Any, **kwargs: t.Any) → Response

  Serialize the given arguments as JSON, and return a `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 `app.json.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.

  Parameters:

    - args – A single value to serialize, or multiple values to treat as a list to serialize.

    - kwargs – Treat as a dict to serialize.

  Changed in version 2.2: Calls `current_app.json.response`, allowing an app to override the behavior.

  Changed in version 2.0.2: `decimal.Decimal` is supported by converting to a string.

  Changed in version 0.11: Added support for serializing top-level arrays. This was a security risk in ancient browsers. See security-json.

  Added in version 0.2.

flask.json.load(fp: IO, **kwargs: Any) → Any

  Deserialize data as JSON read from a file.

  If `current_app` is available, it will use its `app.json.load()` method, otherwise it will use `json.load()`.

  Parameters:

    - fp – A file opened for reading text or UTF-8 bytes.

    - kwargs – Arguments passed to the `load` implementation.

  Changed in version 2.3: The `app` parameter was removed.

  Changed in version 2.2: Calls `current_app.json.load`, allowing an app to override the behavior.

  Changed in version 2.2: The `app` parameter will be removed in Flask 2.3.

  Changed in version 2.0: `encoding` will be removed in Flask 2.1. The file must be text mode, or binary mode with UTF-8 bytes.

flask.json.loads(s: str | bytes, **kwargs: Any) → Any

  Deserialize data as JSON.

  If `current_app` is available, it will use its `app.json.loads()` method, otherwise it will use `json.loads()`.

  Parameters:

    - s – Text or UTF-8 bytes.

    - kwargs – Arguments passed to the `loads` implementation.

  Changed in version 2.3: The `app` parameter was removed.

  Changed in version 2.2: Calls `current_app.json.loads`, allowing an app to override the behavior.

  Changed in version 2.0: `encoding` will be removed in Flask 2.1. The data must be a string or UTF-8 bytes.

  Changed in version 1.0.3: `app` can be passed directly, rather than requiring an app context for configuration.