fleche.metadata =============== .. py:module:: fleche.metadata Attributes ---------- .. autoapisummary:: fleche.metadata._fleche_version fleche.metadata.JSONValue Classes ------- .. autoapisummary:: fleche.metadata.MetaData fleche.metadata.Runtime fleche.metadata.Environment fleche.metadata.Git fleche.metadata.Tags Functions --------- .. autoapisummary:: fleche.metadata._git Module Contents --------------- .. py:data:: _fleche_version :value: 'unknown' .. 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:: Environment Bases: :py:obj:`MetaData` Metadata type for capturing the execution environment. Keys: hostname (str): The machine hostname (``socket.gethostname()``). username (str): The current user (``getpass.getuser()``). cwd (str): The working directory at call time (``os.getcwd()``). fleche_version (str): The fleche package version (``fleche.__version__``); ``"unknown"`` when the package was imported without an installed ``_version.py`` (e.g. an editable checkout without a build). python_version (str): The CPython runtime version (``platform.python_version()``). .. 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: 'environment' 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:function:: _git(*args: str) -> str | None Run ``git`` with *args* and return stripped stdout, or ``None`` on failure. .. py:class:: Git Bases: :py:obj:`MetaData` Metadata type for capturing the git state of the working directory. Keys: root (str | None): Repository top level (``git rev-parse --show-toplevel``). commit (str | None): HEAD commit SHA (``git rev-parse HEAD``). branch (str | None): Current branch name (``git rev-parse --abbrev-ref HEAD``); ``"HEAD"`` when in detached-HEAD state. dirty (bool | None): ``True`` if there are uncommitted changes (tracked or untracked), ``False`` otherwise; ``None`` when not inside a repository or git is unavailable. All keys are ``None`` when not inside a git repository or when the ``git`` executable is missing. .. 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: 'git' 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]