Deterministic hash

[Tom-Kingstone]

Description:

@tg359 has made a method that can be used to convert a list of values into a has in python:

import hashlib
import json
from typing import Any, Union
from ladybug.epw import EPW

# OLD EXT COMFORT METHOD

def _create_hash(
    epw_file: Path,
    ground_material: Union[EnergyMaterial, EnergyMaterialVegetation],
    shade_material: Union[EnergyMaterial, EnergyMaterialVegetation],
) -> str:
    """Create unique hash for this configuration."""
    content = (
        f"{epw_file.name}_{ground_material.identifier}_{shade_material.identifier}"
    )
    return hashlib.shake_256(
        content.encode(
            "utf-8"
        )
    ).hexdigest(10)

# GENERIC METHOD + SUPPORTING METHODS

def deep_sort_dict(obj: dict[Any, Any], sort_lists: bool = True) -> Any:
    """Recursively sort nested dictionaries and lists for consistent ordering."""
    if isinstance(obj, dict):
        return {
            k: deep_sort_dict(v, sort_lists=sort_lists) for k, v in sorted(obj.items())
        }
    elif sort_lists and isinstance(obj, (list, tuple)):
        processed = [deep_sort_dict(x, sort_lists=sort_lists) for x in obj]
        if isinstance(obj, tuple):
            return tuple(
                sorted(
                    processed,
                    key=lambda x: json.dumps(x, sort_keys=True, cls=AllPowerfulEncoder),
                )
            )
        else:
            return sorted(
                processed,
                key=lambda x: json.dumps(x, sort_keys=True, cls=AllPowerfulEncoder),
            )
    else:
        return obj

def deterministic_hash(*values: Any, length: int = 16, algorithm: str = "md5", sort_lists: bool = True) -> int:
    """Create a deterministic hash from one or more values.

    This function produces consistent hash values across Python sessions,
    unlike the built-in hash() function which uses random salting.

    Args:
        *values (Any):
            One or more values to hash. Will be converted to strings and
            concatenated before hashing.
        length (int, optional):
            Number of hexadecimal characters to use from the hash.
            Defaults to 16 (64 bits).
        algorithm (str, optional):
            Hash algorithm to use. Must be supported by hashlib.
            Common options: 'md5', 'sha1', 'sha256', 'sha512'.
            Defaults to 'md5'.
        sort_lists (bool, optional):
            Whether to sort lists and dictionaries recursively before hashing,
            to ensure consistent ordering. Defaults to True.

    Returns:
        int:
            An integer hash value derived from the input values.

    Raises:
        ValueError:
            If the algorithm is not supported by hashlib.

    Example:
        >>> deterministic_hash("hello", "world", 123)
        123456789012345678
        >>> deterministic_hash("hello", "world", 123)  # same result in new session
        123456789012345678
        >>> deterministic_hash("test", length=8)
        12345678

    """

    # validate algorithm
    if algorithm not in hashlib.algorithms_available:
        raise ValueError(
            f"Hash algorithm '{algorithm}' not supported. "
            f"Available: {sorted(hashlib.algorithms_available)}"
        )

    # canonicalize each value
    canonicalized = []
    for v in values:
        if isinstance(v, (dict, list)):
            v = deep_sort_dict(v, sort_lists=sort_lists)
            v = json.dumps(v, sort_keys=True, cls=AllPowerfulEncoder)
        canonicalized.append(str(v))

    concatenated = "".join(canonicalized)
    hasher = hashlib.new(algorithm)
    hasher.update(concatenated.encode("utf-8"))
    hex_digest = hasher.hexdigest()[:length]
    return int(hex_digest, 16)

This would be most useful in toolkits like LadybugTools_Toolkit where ExternalComfort simulations require identifiers to be under 100 characters, but will be placed in this toolkit in case other tools require it.