uuid-utils

Warnings

• breaking The byte-order for `uuid1` and `uuid6` was fixed in version 0.14.1. If you relied on the previous, incorrect byte-order in earlier versions, this change may break compatibility with existing data or systems.
  Fix: Review any code or stored UUIDs generated with `uuid1` or `uuid6` from versions prior to 0.14.1. Ensure that the new, correct byte order is compatible with your application's requirements.
• deprecated Support for Python 3.7 was dropped in version 0.7.0. Users on Python 3.7 will not be able to upgrade to newer versions of `uuid-utils`.
  Fix: Upgrade to Python 3.8 or newer to continue receiving updates and security fixes for `uuid-utils`.
• gotcha The default `UUID` class returned by `uuid_utils` is a custom class. If you require standard library `uuid.UUID` instances (e.g., for ORMs like Django), you must import from `uuid_utils.compat`.
  Fix: Instead of `import uuid_utils as uuid`, use `from uuid_utils.compat import uuid1, uuid3, uuid4, uuid5, uuid6, uuid7, uuid8, UUID` or `import uuid_utils.compat as uuid` when standard library `UUID` instances are needed.
• gotcha The behavior of `getnode` was changed in version 0.14.0 to be compatible with Python's standard library `uuid.getnode()`. If your application relied on the specific behavior of `getnode` in earlier `uuid-utils` versions, this might introduce subtle changes.
  Fix: Verify that `getnode()` behavior is consistent with your expectations if you were using it prior to version 0.14.0. The new behavior aligns with `stdlib`.
• gotcha While `uuid-utils` explicitly calls to 'reseed RNG in fork process' (since 0.14.0) to improve multiprocessing safety for random UUIDs, standard library's `uuid.uuid4()` has historically had issues where child processes generated identical UUIDs if the RNG was not reseeded. Although `uuid-utils` addresses this, always test UUID generation thoroughly in multiprocessing environments to ensure uniqueness.
  Fix: Ensure `uuid-utils` is at least 0.14.0 for improved multiprocessing handling. For critical applications, consider explicitly re-seeding the random number generator in child processes if you encounter collisions, or use `uuid.uuid1()` or `uuid.uuid7()` which are time-based and generally more robust in distributed systems for ordering and uniqueness.

Install

• pip install uuid-utils Install with pip

Imports

• uuid

  import uuid_utils as uuid

  Common pattern for a direct drop-in replacement, making most existing code compatible.
• uuid4

  from uuid_utils import uuid4

• UUID

  from uuid_utils.compat import UUID

  Use the `compat` module if you require standard library `uuid.UUID` instances (e.g., for Django ORM compatibility). This incurs a slight performance penalty but is still faster than `stdlib` UUID.

Quickstart

This quickstart demonstrates how to generate various UUID versions using `uuid-utils`, including random (v4), time-ordered (v7), and name-based (v5) UUIDs. It also shows how to use the compatibility layer to obtain standard library `uuid.UUID` instances when required.

import uuid_utils as uuid

# Generate a random UUID (Version 4)
random_uuid = uuid.uuid4()
print(f"Random UUID (v4): {random_uuid}")

# Generate a time-ordered UUID (Version 7)
time_ordered_uuid = uuid.uuid7()
print(f"Time-ordered UUID (v7): {time_ordered_uuid}")

# Generate a name-based UUID using SHA-1 hash (Version 5)
namespace_dns = uuid.NAMESPACE_DNS
name_uuid = uuid.uuid5(namespace_dns, 'example.com')
print(f"Name-based UUID (v5) for 'example.com': {name_uuid}")

# To get a standard library UUID instance (e.g. for Django):
from uuid_utils.compat import uuid4 as compat_uuid4
compat_instance = compat_uuid4()
print(f"Compat UUID (v4): {compat_instance}")
print(f"Is compat instance a standard uuid.UUID? {isinstance(compat_instance, uuid.UUID)}")