json
====

.. py:module:: json

.. autoapi-nested-parse::

   Utility functions related to json.



Attributes
----------

.. autoapisummary::

   json.JsonDataSelf


Classes
-------

.. autoapisummary::

   json.JsonError
   json.JsonDataInvalidJsonError
   json.JsonData


Functions
---------

.. autoapisummary::

   json.dump_to_json_file
   json.load_from_json_file


Module Contents
---------------

.. py:data:: JsonDataSelf

.. py:class:: JsonError

   Bases: :py:obj:`e3.error.E3Error`


.. py:class:: JsonDataInvalidJsonError

   Bases: :py:obj:`e3.error.E3Error`


   An error thrown when input data string does not represent a dictionary.


.. py:class:: JsonData

   Bases: :py:obj:`abc.ABC`


   An object to represent JSON data content.


   .. py:method:: as_dict() -> dict[str, object]
      :abstractmethod:


      Return the dict representation of this JSON data object.



   .. py:method:: __eq__(other: object) -> bool

      Check if this JSON data is identical to *other*.

      :param other: The object to compare this JSON data with.

      :return: A :class:`bool` set to **True** if both JSON data are
          identical, **False** if they are not, or if *other* is not a
          :class:`JsonData` object.



   .. py:method:: as_json() -> str

      Return a JSON string representing this JSON data.

      .. seealso:: :func:`python:json.dumps`



   .. py:method:: from_dict(obj: dict) -> JsonDataSelf
      :classmethod:


      Load a dictionary as a JSON data object.

      :param obj: The dictionary to initialize the JSON data object with.

      :return: A new :class:`JsonData` object initialized with
          values from the input dictionary.



   .. py:method:: from_json(content: str) -> JsonDataSelf
      :classmethod:


      Load a JSON string as a JSON data object.

      As this method calls for :meth:`from_dict`,  the input *content* string
      **MUST** represent a dictionary. If that's not the case, a
      :class:`JsonDataInvalidJsonError` is thrown.

      :param content: The JSON string to initialize the JSON data object with.

      :return: A new :class:`JsonData` object initialized with
          values from the input dictionary.

      :raise: :class:`JsonDataInvalidJsonError` when *content* string does not
          represent a dictionary.

      .. seealso:: :meth:`as_json`, :meth:`from_dict`



.. py:function:: dump_to_json_file(path: str, obj: Any) -> None

   Dump a Python object to a json file.

   :param path: path to the json file
   :param obj: a Python object that can serialized to JSON


.. py:function:: load_from_json_file(path: str, default: Any = None, ignore_non_existing: bool = True) -> Any

   Load a Python object from a JSON file.

   :param path: json file path
   :param default: default value returned if ignore_non_existing is True and
       the specified file does not exist.
   :param ignore_non_existing: if False raise JsonError if the file does not
       exist, otherwise return default value
   :return: a Python object


