Source code for bhf_smarthealth.utils.identifiers

"""This module contains utility functions to generate / modify identifiers"""

import uuid
import pandas as pd

from bhf_smarthealth.config import NAMESPACE




def generate_deterministic_uuid_from_args(
    *args, null_placeholder: str = "None", namespace: uuid.UUID = NAMESPACE
) -> str:
    """Generate a UUID5 based on the SHA-1 hash of a namespace identifier (which is a UUID configured in the central config.py file) and a "name", where the name is any number of args.  NULL values are replaced by a placeholder value to ensure consistency.

    Parameters
    ----------
    null_placeholder : str, optional
        Placeholder value to replace NULL values with, by default "None"
    namespace : uuid.UUID
        Persistent project namespace required for deterministic uuid generation


    Returns
    -------
    str
        The hashed string with {num_chars} number of characters

    Warnings
    --------
    This method of hashing an input is NOT secure and it intended only for the purpose of generating a performance-optimised, deterministic database key. It should NOT be used for data pseudonymisation.
    """
    # ensure that Null / None values are handled the same way
    validated_args = [
        str(arg).lower() if not pd.isna(arg) else null_placeholder.lower()
        for arg in args
    ]

    # must join strings with a delimiter to prevent "value bleeding" e.g. 1 + 23 vs 12 + 3
    payload = "|".join(map(str, validated_args)).encode("utf-8")

    return str(uuid.uuid5(namespace=namespace, name=payload))





def generate_nil_uuid() -> str:
    """Generate placeholder UUID value of entirely zeroes. Can be used as a 'sentinel value' instead of a NULL or None value.

    Returns
    -------
    str
        UUID value in the form 00000000-0000-0000-0000-000000000000

    """

    return str(uuid.UUID(int=0))