json_utils
==========

.. py:module:: quantify_scheduler.json_utils 

.. autoapi-nested-parse::

   Module containing quantify JSON utilities.



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

Classes
~~~~~~~

.. autoapisummary::

   quantify_scheduler.json_utils.JSONSchemaValMixin
   quantify_scheduler.json_utils.SchedulerJSONDecoder
   quantify_scheduler.json_utils.SchedulerJSONEncoder



Functions
~~~~~~~~~

.. autoapisummary::

   quantify_scheduler.json_utils.validate_json
   quantify_scheduler.json_utils.load_json_schema
   quantify_scheduler.json_utils.load_json_validator
   quantify_scheduler.json_utils._get_type_from_string_deprecated



Attributes
~~~~~~~~~~

.. autoapisummary::

   quantify_scheduler.json_utils.current_python_version
   quantify_scheduler.json_utils.lru_cache
   quantify_scheduler.json_utils.DEFAULT_TYPES


.. py:data:: current_python_version

.. py:data:: lru_cache

.. py:data:: DEFAULT_TYPES

.. py:function:: validate_json(data, schema)

   Validate schema using jsonschema-rs.


.. py:function:: load_json_schema(relative_to: Union[str, pathlib.Path], filename: str)

   Load a JSON schema from file. Expects a 'schemas' directory in the same directory
   as ``relative_to``.

   .. tip::

       Typical usage of the form
       ``schema = load_json_schema(__file__, 'definition.json')``

   :param relative_to: the file to begin searching from
   :param filename: the JSON file to load

   :returns: the schema
   :rtype: dict


.. py:function:: load_json_validator(relative_to: Union[str, pathlib.Path], filename: str) -> Callable

   Load a JSON validator from file. Expects a 'schemas' directory in the same directory
   as ``relative_to``.


   :param relative_to: the file to begin searching from
   :param filename: the JSON file to load

   :returns: The validator
   :rtype: Callable


.. py:exception:: UnknownDeserializationTypeError

   Bases: :py:obj:`Exception`


   Raised when an unknown deserialization type is encountered.


.. py:class:: JSONSchemaValMixin

   A mixin that adds validation utilities to classes that have
   a data attribute like a :class:`UserDict` based on JSONSchema.

   This requires the class to have a class variable "schema_filename"


   .. py:attribute:: schema_filename
      :type:  str


   .. py:method:: is_valid(object_to_be_validated) -> bool
      :classmethod:


      Checks if the object is valid according to its schema.

      :raises fastjsonschema.JsonSchemaException: if the data is invalid



.. py:class:: SchedulerJSONDecoder(*args, **kwargs)

   Bases: :py:obj:`json.JSONDecoder`


   The Quantify Scheduler JSONDecoder.

   The SchedulerJSONDecoder is used to convert a string with JSON content into
   instances of classes in quantify-scheduler.

   For a few types, :data:`~.DEFAULT_TYPES` contains the mapping from type name to the
   python object. This dictionary can be expanded with classes from modules specified
   in the keyword argument ``modules``.

   Classes not contained in :data:`~.DEFAULT_TYPES` by default must implement
   ``__getstate__``, such that it returns a dictionary containing at least the keys
   ``"deserialization_type"`` and ``"data"``, and ``__setstate__``, which should be
   able to parse the data from ``__getstate__``.

   The value of ``"deserialization_type"`` must be either the name of the class
   specified in :data:`~.DEFAULT_TYPES` or the fully qualified name of the class, which
   can be obtained from
   :func:`~quantify_scheduler.helpers.importers.export_python_object_to_path_string`.

   :keyword modules: A list of custom modules containing serializable classes, by default []
   :kwtype modules: List[ModuleType], *optional*


   .. py:attribute:: _classes
      :type:  Dict[str, Type[Any]]


   .. py:attribute:: extended_modules
      :type:  List[types.ModuleType]


   .. py:attribute:: invalid_modules


   .. py:method:: decode_dict(obj: Dict[str, Any]) -> Union[Dict[str, Any], numpy.ndarray, type, qcodes.instrument.Instrument]

      Returns the deserialized JSON dictionary.

      :param obj: The dictionary to deserialize.

      :returns: The deserialized result.



   .. py:method:: custom_object_hook(obj: object) -> object

      The ``object_hook`` hook will be called with the result of every JSON object
      decoded and its return value will be used in place of the given ``dict``.

      :param obj: A pair of JSON objects.

      :returns: The deserialized result.



   .. py:method:: _get_type_from_string(deserialization_type: str) -> Type

      Get the python type based on the description string.

      The following methods are tried, in order:

          1. Try to find the string in :data:`~.DEFAULT_TYPES` or the extended modules
              passed to this class' initializer.
          2. Try to import the type. This works only if ``deserialization_type`` is
              formatted as a dot-separated path to the type. E.g.
              ``quantify_scheduler.json_utils.SchedulerJSONDecoder``.
          3. (deprecated) Try to find the class by its ``__name__`` in a predefined
              selection of types present in ``quantify_scheduler``.

      :param deserialization_type: Description of a type.

      :raises UnknownDeserializationTypeError: If the type cannot be found by any of the methods described.

      :returns: The ``Type`` found.
      :rtype: Type



.. py:function:: _get_type_from_string_deprecated(deserialization_type: str) -> Type

.. py:class:: SchedulerJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

   Bases: :py:obj:`json.JSONEncoder`


   Custom JSONEncoder which encodes a Quantify Scheduler object into a JSON file format
   string.


   .. py:method:: default(o)

      Overloads the json.JSONEncoder default method that returns a serializable
      object. It will try 3 different serialization methods which are, in order,
      check if the object is to be serialized to a string using repr. If not, try
      to use ``__getstate__``. Finally, try to serialize the ``__dict__`` property.