dacapo.store.conversion_hooks
=============================

.. py:module:: dacapo.store.conversion_hooks


Functions
---------

.. autoapisummary::

   dacapo.store.conversion_hooks.register_hierarchy_hooks
   dacapo.store.conversion_hooks.register_hooks
   dacapo.store.conversion_hooks.cls_fun


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

.. py:function:: register_hierarchy_hooks(converter)

   Central place to register type hierarchies for conversion.

   :param converter: The converter to register the hooks with.
   :type converter: Converter

   :raises TypeError: If ``cls`` is not a class.

   .. rubric:: Example

   If class ``A`` is the base of class ``B``, and
   ``converter.register_hierarchy(A, lambda typ: eval(typ))`` has been
   called, the dictionary ``y = converter.unstructure(x)`` will
   contain a ``__type__`` field that is ``'A'`` if ``x = A()`` and
   ``B`` if ``x = B()``.

   This ``__type__`` field is then used by ``x =
   converter.structure(y, A)`` to recreate the concrete type of ``x``.

   .. note::

      This method is used to register a class hierarchy for typed
      structure/unstructure conversion. For each class in the hierarchy
      under (including) ``cls``, this will store an additional
      ``__type__`` attribute (a string) in the object dictionary. This
      ``__type__`` string will be the concrete class of the object, and
      will be used to structure the dictionary back into an object of the
      correct class.
      
      For this to work, this function needs to know how to convert a
      ``__type__`` string back into a class, for which it used the
      provided ``cls_fn``.


.. py:function:: register_hooks(converter)

   Central place to register all conversion hooks with the given
   converter.

   :param converter: The converter to register the hooks with.
   :type converter: Converter

   :raises TypeError: If ``cls`` is not a class.

   .. rubric:: Example

   If class ``A`` is the base of class ``B``, and
   ``converter.register_hierarchy(A, lambda typ: eval(typ))`` has been
   called, the dictionary ``y = converter.unstructure(x)`` will
   contain a ``__type__`` field that is ``'A'`` if ``x = A()`` and
   ``B`` if ``x = B()``.

   This ``__type__`` field is then used by ``x =
   converter.structure(y, A)`` to recreate the concrete type of ``x``.

   .. note::

      This method is used to register a class hierarchy for typed
      structure/unstructure conversion. For each class in the hierarchy
      under (including) ``cls``, this will store an additional
      ``__type__`` attribute (a string) in the object dictionary. This
      ``__type__`` string will be the concrete class of the object, and
      will be used to structure the dictionary back into an object of the
      correct class.
      
      For this to work, this function needs to know how to convert a
      ``__type__`` string back into a class, for which it used the
      provided ``cls_fn``.


.. py:function:: cls_fun(typ)

   Convert a type string into the corresponding class. The class must be
   visible to this module (hence the star imports at the top).

   :param typ: The type string to convert.
   :type typ: str

   :returns: The class corresponding to the type string.
   :rtype: class

   :raises NameError: If the class is not visible to this module.

   .. rubric:: Example

   ``cls_fun('TaskConfig')`` will return the class ``TaskConfig``.

   .. note::

      This function is used to convert a type string back into a class. It is
      used in conjunction with the ``register_hierarchy`` function to
      register a class hierarchy for typed structure/unstructure conversion.