UUID Utils
Utility class providing optimized UUID generation and conversions used across the Norman platform.
This class focuses on: - Generating sequential (time-ordered) UUIDs optimized for MySQL indexing - Reordering UUID bytes for improved locality in B-tree indexes - Converting UUIDs between bytes, integers, and string representations
Methods
bytes_to_int(id_bytes) staticmethod
Convert a 16-byte UUID representation into its integer form.
Parameters
id_bytes (
bytes) 16-byte UUID.
Returns
int - Integer representing the UUID.
bytes_to_str_id(id_bytes) staticmethod
Convert a 16-byte UUID into a decimal string representation. Useful for serializing integer-based UUIDs to JSON or logs.
Parameters
id_bytes (
bytes) 16-byte UUID.
Returns
str - Decimal string encoding of the UUID.
int_to_bytes(id_int) staticmethod
Convert an integer UUID representation back into 16 bytes.
Parameters
id_int (
int) Integer UUID.
Returns
bytes - 16-byte big-endian UUID.
optimized_unique_id(unique_id=None) staticmethod
Generate a sequential, index-optimized UUID in 16-byte binary form.
If no UUID is provided, a new uuid.uuid1() is created. The raw bytes of the UUID are then reordered to move the timestamp portion to the beginning, improving MySQL insertion locality and reducing B-tree fragmentation.
Parameters
unique_id (
uuid.UUID | None) Optional existing UUID. IfNone, a new UUID1 is generated automatically.
Returns
bytes - 16-byte reordered UUID suitable for database storage.
This produces IDs that grow in natural chronological order.
str_id_to_bytes(id_str) staticmethod
Convert a decimal UUID string back into 16-byte form.
Parameters
id_str (
str) Decimal string produced frombytes_to_str_id().
Returns
bytes - 16-byte UUID.