Release mode

For publishing a data product, a release mode ensures reproducibility by associating the product with a specific Git commit hash. This commit hash serves as a unique identifier for the exact version of the EL-PASO code used to generate the data.

By linking the data to a precise point in the Git history, anyone can retrieve the identical code version and replicate the results, guaranteeing that the data product is traceable and verifiable.

Before release mode can be activated, the EL-PASO repository must not contain any changes which are not commited to the repository.

Under release mode, additional metadata of the author who processed the data is also storred as metadata.

el_paso.release_mode

Functions:

el_paso.release_mode.activate_release_mode

activate_release_mode

Activates the package's release mode and validates the repository state.

This function enables a special mode for data processing that records key information about the execution environment. It checks if the package is installed and validates that the Git repository is in a clean state (no uncommitted changes) unless dirty_ok is set to True. Upon successful activation, it stores metadata about the user, version, and commit hash. This information is appended to the metadata of any processed variables.

Parameters:

Name	Type	Description	Default
user_name	str	The name of the user activating release mode.	required
email_address	str	The email address of the user.	required
el_paso_repository_path	str | Path	The path to the EL-PASO Git repository.	required
dirty_ok	bool	If True, allows activation even if the repository has uncommitted changes. Defaults to False.	False

Raises:

Type	Description
PackageNotFoundError	If the 'el_paso' package is not found in the Python environment, indicating it's not properly installed.
ValueError	If the Git repository is not clean and dirty_ok is False.

Source code in el_paso/release_mode.py

def activate_release_mode(
    user_name: str, email_address: str, el_paso_repository_path: str | Path, *, dirty_ok: bool = False
) -> None:
    """Activates the package's release mode and validates the repository state.

    This function enables a special mode for data processing that records key
    information about the execution environment. It checks if the package is
    installed and validates that the Git repository is in a clean state (no
    uncommitted changes) unless `dirty_ok` is set to `True`. Upon successful
    activation, it stores metadata about the user, version, and commit hash.
    This information is appended to the metadata of any processed variables.

    Args:
        user_name (str): The name of the user activating release mode.
        email_address (str): The email address of the user.
        el_paso_repository_path (str | Path): The path to the EL-PASO Git repository.
        dirty_ok (bool, optional): If `True`, allows activation even if the
            repository has uncommitted changes. Defaults to `False`.

    Raises:
        importlib.metadata.PackageNotFoundError: If the 'el_paso' package is not
            found in the Python environment, indicating it's not properly installed.
        ValueError: If the Git repository is not clean and `dirty_ok` is `False`.
    """
    try:
        el_paso_version = importlib.metadata.version("el_paso")
    except importlib.metadata.PackageNotFoundError:
        logger.exception("EL-PASO has to be installed when release mode is used!")
        raise

    el_paso_repo = git.Repo(el_paso_repository_path)
    commit_hash = el_paso_repo.head.commit.hexsha

    if el_paso_repo.is_dirty(index=True, working_tree=True, untracked_files=True):
        if dirty_ok:
            logger.warning("Dirty repository used for processing data in release mode!", stacklevel=2)
        else:
            msg = "Your EL-PASO repository contains changes! Please push your changes to process data in release mode!"
            raise ValueError(msg)

    date_now = datetime.now(timezone.utc).now()
    date_now_str = date_now.strftime("%d-%b-%Y")

    ep._release_msg = (
        f"This variable was processed using the EL-PASO release mode on {date_now_str}.\n"
        f"User name: {user_name}, email address: {email_address}.\n"
        f"EL-PASO version: {el_paso_version}, git commit: {commit_hash}."
    )

    ep._release_mode = True

el_paso.release_mode.get_release_msg

get_release_msg

Retrieves the message associated with the package's release mode.

This message contains metadata about the execution environment, including user information, version, and commit hash, if release mode is active.

Returns:

Name	Type	Description
str	str	The release mode message if active, otherwise an empty string.

Source code in el_paso/release_mode.py

def get_release_msg() -> str:
    """Retrieves the message associated with the package's release mode.

    This message contains metadata about the execution environment, including
    user information, version, and commit hash, if release mode is active.

    Returns:
        str: The release mode message if active, otherwise an empty string.
    """
    return ep._release_msg

el_paso.release_mode.is_in_release_mode

is_in_release_mode

Checks if the package's release mode is currently active.

Returns:

Name	Type	Description
bool	bool	True if release mode is active, False otherwise.

Source code in el_paso/release_mode.py

def is_in_release_mode() -> bool:
    """Checks if the package's release mode is currently active.

    Returns:
        bool: `True` if release mode is active, `False` otherwise.
    """
    return ep._release_mode