fleche.metadata
===============

.. py:module:: fleche.metadata


Attributes
----------

.. autoapisummary::

   fleche.metadata.JSONValue


Classes
-------

.. autoapisummary::

   fleche.metadata.MetaData
   fleche.metadata.Runtime
   fleche.metadata.Tags


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

.. py:type:: JSONValue
   :canonical: str | int | float | bool | None | list['JSONValue'] | dict[str, 'JSONValue']


.. py:class:: MetaData

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


   Abstract base class for defining metadata types.

   Implementations must return only JSON-serializable values from pre() and post().
   That means scalars (str, int, float, bool, None), lists of those, or dicts with str keys
   and JSON-serializable values.


   .. py:method:: pre(call: fleche.call.Call) -> dict[str, JSONValue]

      Hook for collecting metadata before the function execution.

      :param call: The call object of the decorated function.
      :type call: Call

      :returns: A flat dictionary of JSON-serializable metadata collected before execution.
      :rtype: dict[str, JSONValue]



   .. py:method:: post(pre: dict[str, JSONValue], call: fleche.call.Call) -> dict[str, JSONValue]

      Hook for collecting metadata after the function execution.

      The return value of the function is available on the `call.result` attribute.

      :param pre: Metadata collected during the pre-execution phase.
      :type pre: dict[str, JSONValue]
      :param call: The call object of the decorated function.
      :type call: Call

      :returns: A flat dictionary of JSON-serializable metadata collected after execution.
      :rtype: dict[str, JSONValue]



   .. py:property:: keys
      :type: dict[str, type]

      :abstractmethod:


      Defines the schema of the metadata, mapping metadata keys to their expected types.

      :returns: A dictionary representing the metadata schema.
      :rtype: dict[str, type]


   .. py:property:: name
      :type: str

      :abstractmethod:


      The unique name of this metadata type.

      :returns: The name of the metadata type.
      :rtype: str


.. py:class:: Runtime

   Bases: :py:obj:`MetaData`


   Metadata type for capturing runtime information.

   Keys:
       timestart (float): The timestamp when the execution started.
       timestop (float): The timestamp when the execution stopped.
       walltime (float): The total execution time in seconds.

   .. rubric:: Notes

   Values are JSON-serializable.


   .. py:method:: pre(call: fleche.call.Call) -> dict[str, Any]

      Records the start time before function execution.



   .. py:method:: post(pre: dict[str, Any], call: fleche.call.Call) -> dict[str, Any]

      Records the stop time and calculates the wall time after function execution.



   .. py:attribute:: name
      :type:  str
      :value: 'runtime'


      The unique name of this metadata type.

      :returns: The name of the metadata type.
      :rtype: str


   .. py:attribute:: keys
      :type:  dict[str, type]

      Defines the schema of the metadata, mapping metadata keys to their expected types.

      :returns: A dictionary representing the metadata schema.
      :rtype: dict[str, type]


.. py:class:: Tags

   Bases: :py:obj:`MetaData`


   Metadata type for storing arbitrary tags.

   For each key in the ``tags`` dictionary, a new metadata column is created.

   Keys:
       tags (dict): A dictionary of user-defined tags.

   .. rubric:: Notes

   Tag values must be JSON-serializable.


   .. py:attribute:: tags
      :type:  dict[str, Any]


   .. py:method:: pre(call: fleche.call.Call) -> dict[str, Any]

      Hook for collecting metadata before the function execution.

      :param call: The call object of the decorated function.
      :type call: Call

      :returns: A flat dictionary of JSON-serializable metadata collected before execution.
      :rtype: dict[str, JSONValue]



   .. py:attribute:: name
      :type:  str
      :value: 'tags'


      The unique name of this metadata type.

      :returns: The name of the metadata type.
      :rtype: str


   .. py:property:: keys

      Defines the schema of the metadata, mapping metadata keys to their expected types.

      :returns: A dictionary representing the metadata schema.
      :rtype: dict[str, type]