fleche.metadata

Attributes

`_fleche_version`
`JSONValue`
`CONFIGURABLE`

Classes

`MetaData`	Abstract base class for defining metadata types.
`Runtime`	Metadata type for capturing runtime information.
`Environment`	Metadata type for capturing the execution environment.
`Git`	Metadata type for capturing the git state of the working directory.
`Tags`	Metadata type for storing arbitrary tags.

Functions

`configurable`(→ type[MetaData])	Register a MetaData subclass as zero-arg configurable and set its name.
`_git`(→ str \| None)	Run `git` with args and return stripped stdout, or `None` on failure.

Module Contents

fleche.metadata._fleche_version = 'unknown'[source]

type fleche.metadata.JSONValue = str | int | float | bool | None | list['JSONValue'] | dict[str, 'JSONValue'][source]

class fleche.metadata.MetaData[source]

Bases: 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.

pre(call: fleche.call.Call) → dict[str, JSONValue][source]

Hook for collecting metadata before the function execution.

Parameters:: call (Call) – The call object of the decorated function.
Returns:: A flat dictionary of JSON-serializable metadata collected before execution.
Return type:: dict[str, JSONValue]

post(pre: dict[str, JSONValue], call: fleche.call.Call) → dict[str, JSONValue][source]

Hook for collecting metadata after the function execution.

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

Parameters:

pre (dict[str, JSONValue]) – Metadata collected during the pre-execution phase.
call (Call) – The call object of the decorated function.

Returns:

A flat dictionary of JSON-serializable metadata collected after execution.

Return type:

dict[str, JSONValue]

property keys: dict[str, type][source]

Abstractmethod:

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

Returns:: A dictionary representing the metadata schema.
Return type:: dict[str, type]

name: str[source]: The unique name of this metadata type.

fleche.metadata.CONFIGURABLE: dict[str, type[MetaData]][source]

fleche.metadata.configurable(cls: type[MetaData]) → type[MetaData][source]

Register a MetaData subclass as zero-arg configurable and set its name.

Sets cls.name to cls.__name__.lower() and adds the class to the CONFIGURABLE registry under cls.__name__, making it selectable from the TOML [default] metadata = [...] list. Classes that require constructor arguments (e.g. Tags) must not be decorated.

class fleche.metadata.Runtime[source]

Bases: 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.

Notes

Values are JSON-serializable.

pre(call: fleche.call.Call) → dict[str, Any][source]: Records the start time before function execution.

post(pre: dict[str, Any], call: fleche.call.Call) → dict[str, Any][source]: Records the stop time and calculates the wall time after function execution.

keys: dict[str, type][source]

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

Returns:: A dictionary representing the metadata schema.
Return type:: dict[str, type]

class fleche.metadata.Environment[source]

Bases: 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()).

pre(call: fleche.call.Call) → dict[str, Any][source]

Hook for collecting metadata before the function execution.

Parameters:: call (Call) – The call object of the decorated function.
Returns:: A flat dictionary of JSON-serializable metadata collected before execution.
Return type:: dict[str, JSONValue]

keys: dict[str, type][source]

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

Returns:: A dictionary representing the metadata schema.
Return type:: dict[str, type]

fleche.metadata._git(*args: str) → str | None[source]: Run git with args and return stripped stdout, or None on failure.

class fleche.metadata.Git[source]

Bases: 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.

pre(call: fleche.call.Call) → dict[str, Any][source]

Hook for collecting metadata before the function execution.

Parameters:: call (Call) – The call object of the decorated function.
Returns:: A flat dictionary of JSON-serializable metadata collected before execution.
Return type:: dict[str, JSONValue]

keys: dict[str, type][source]

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

Returns:: A dictionary representing the metadata schema.
Return type:: dict[str, type]

class fleche.metadata.Tags[source]

Bases: 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.

Notes

Tag values must be JSON-serializable.

tags: dict[str, Any][source]

pre(call: fleche.call.Call) → dict[str, Any][source]

Hook for collecting metadata before the function execution.

Parameters:: call (Call) – The call object of the decorated function.
Returns:: A flat dictionary of JSON-serializable metadata collected before execution.
Return type:: dict[str, JSONValue]

name: str = 'tags'[source]: The unique name of this metadata type.

property keys[source]

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

Returns:: A dictionary representing the metadata schema.
Return type:: dict[str, type]