Skip to content

Utils

provide.foundation.crypto.utils

TODO: Add module docstring.

Functions

compare_hash 

compare_hash(hash1: str, hash2: str) -> bool

Compare two hash values in a case-insensitive manner.

Parameters:

Name Type Description Default
hash1 str

First hash value

 required
hash2 str

Second hash value

 required

Returns:

Type Description
bool

True if hashes match (case-insensitive)
Source code in provide/foundation/crypto/utils.py 
49
50
51
52
53
54
55
56
57
58
59
60
def compare_hash(hash1: str, hash2: str) -> bool:
    """Compare two hash values in a case-insensitive manner.

    Args:
        hash1: First hash value
        hash2: Second hash value

    Returns:
        True if hashes match (case-insensitive)

    """
    return hash1.lower() == hash2.lower()

format_hash 

format_hash(
    hash_value: str,
    group_size: int = 8,
    groups: int = 0,
    separator: str = " ",
) -> str

Format a hash value for display.

Parameters:

Name Type Description Default
hash_value str

Hash value to format

 required
group_size int

Number of characters per group

 8
groups int

Number of groups to show (0 for all)

 0
separator str

Separator between groups

 ' '

Returns:

Type Description
str

Formatted hash string

Examples:

>>> format_hash("abc123def456", group_size=4, separator="-")
"abc1-23de-f456"
>>> format_hash("abc123def456", group_size=4, groups=2)
"abc1 23de"
Source code in provide/foundation/crypto/utils.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def format_hash(
    hash_value: str,
    group_size: int = 8,
    groups: int = 0,
    separator: str = " ",
) -> str:
    """Format a hash value for display.

    Args:
        hash_value: Hash value to format
        group_size: Number of characters per group
        groups: Number of groups to show (0 for all)
        separator: Separator between groups

    Returns:
        Formatted hash string

    Examples:
        >>> format_hash("abc123def456", group_size=4, separator="-")
        "abc1-23de-f456"
        >>> format_hash("abc123def456", group_size=4, groups=2)
        "abc1 23de"

    """
    if group_size <= 0:
        return hash_value

    formatted_parts = []
    for i in range(0, len(hash_value), group_size):
        formatted_parts.append(hash_value[i : i + group_size])
        if groups > 0 and len(formatted_parts) >= groups:
            break

    return separator.join(formatted_parts)

hash_name 

hash_name(name: str) -> int

Generate a 64-bit hash of a string for fast lookup.

This is useful for creating numeric identifiers from strings.

Parameters:

Name Type Description Default
name str

String to hash

 required

Returns:

Type Description
int

64-bit integer hash
Source code in provide/foundation/crypto/utils.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def hash_name(name: str) -> int:
    """Generate a 64-bit hash of a string for fast lookup.

    This is useful for creating numeric identifiers from strings.

    Args:
        name: String to hash

    Returns:
        64-bit integer hash

    """
    # Use first 8 bytes of SHA256 for good distribution
    hash_bytes = hashlib.sha256(name.encode("utf-8")).digest()[:8]
    return int.from_bytes(hash_bytes, byteorder="little")

hash_to_int 

hash_to_int(hash_value: str) -> int

Convert a hex hash string to an integer.

Parameters:

Name Type Description Default
hash_value str

Hex hash string

 required

Returns:

Type Description
int

Integer representation of the hash
Source code in provide/foundation/crypto/utils.py 
120
121
122
123
124
125
126
127
128
129
130
def hash_to_int(hash_value: str) -> int:
    """Convert a hex hash string to an integer.

    Args:
        hash_value: Hex hash string

    Returns:
        Integer representation of the hash

    """
    return int(hash_value, 16)

int_to_hash 

int_to_hash(value: int, length: int | None = None) -> str

Convert an integer to a hex hash string.

Parameters:

Name Type Description Default
value int

Integer value

 required
length int | None

Desired length (will pad with zeros)

 None

Returns:

Type Description
str

Hex string representation
Source code in provide/foundation/crypto/utils.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def int_to_hash(value: int, length: int | None = None) -> str:
    """Convert an integer to a hex hash string.

    Args:
        value: Integer value
        length: Desired length (will pad with zeros)

    Returns:
        Hex string representation

    """
    hex_str = format(value, "x")
    if length and len(hex_str) < length:
        hex_str = hex_str.zfill(length)
    return hex_str

is_valid_hash 

is_valid_hash(
    hash_value: str, algorithm: str | None = None
) -> bool

Check if a string is a valid hash value.

Parameters:

Name Type Description Default
hash_value str

String to check

 required
algorithm str | None

Optional algorithm to validate length against

 None

Returns:

Type Description
bool

True if string appears to be a valid hash
Source code in provide/foundation/crypto/utils.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def is_valid_hash(hash_value: str, algorithm: str | None = None) -> bool:
    """Check if a string is a valid hash value.

    Args:
        hash_value: String to check
        algorithm: Optional algorithm to validate length against

    Returns:
        True if string appears to be a valid hash

    """
    # Check if it's a valid hex string
    try:
        int(hash_value, 16)
    except ValueError:
        return False

    # If algorithm specified, check length
    if algorithm:
        from provide.foundation.crypto.algorithms import (
            get_digest_size,
            validate_algorithm,
        )

        try:
            validate_algorithm(algorithm)
            expected_length = get_digest_size(algorithm) * 2  # hex is 2 chars per byte
            return len(hash_value) == expected_length
        except Exception:
            return False

    return True

quick_hash 

quick_hash(data: bytes) -> int

Generate a quick non-cryptographic hash for lookups.

This uses Python's built-in hash function which is fast but not cryptographically secure. Use only for hash tables and caching.

Parameters:

Name Type Description Default
data bytes

Data to hash

 required

Returns:

Type Description
int

32-bit hash value
Source code in provide/foundation/crypto/utils.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def quick_hash(data: bytes) -> int:
    """Generate a quick non-cryptographic hash for lookups.

    This uses Python's built-in hash function which is fast but not
    cryptographically secure. Use only for hash tables and caching.

    Args:
        data: Data to hash

    Returns:
        32-bit hash value

    """
    # Use Python's built-in hash for speed, mask to 32 bits
    return hash(data) & 0xFFFFFFFF

truncate_hash 

truncate_hash(
    hash_value: str, length: int = 16, suffix: str = "..."
) -> str

Truncate a hash for display purposes.

Parameters:

Name Type Description Default
hash_value str

Hash value to truncate

 required
length int

Number of characters to keep

 16
suffix str

Suffix to append

 '...'

Returns:

Type Description
str

Truncated hash string

Examples:

>>> truncate_hash("abc123def456789", length=8)
"abc123de..."
Source code in provide/foundation/crypto/utils.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def truncate_hash(hash_value: str, length: int = 16, suffix: str = "...") -> str:
    """Truncate a hash for display purposes.

    Args:
        hash_value: Hash value to truncate
        length: Number of characters to keep
        suffix: Suffix to append

    Returns:
        Truncated hash string

    Examples:
        >>> truncate_hash("abc123def456789", length=8)
        "abc123de..."

    """
    if len(hash_value) <= length:
        return hash_value
    return hash_value[:length] + suffix