DOCSEARCHbyAlgolia
Submit Docs

uuid-utils

repository·main·Indexed 18 days ago

https://github.com/aminalaee/uuid-utils

A high-performance, Rust-powered replacement for Python's standard uuid module. It supports standard UUID versions (1, 3, 4, 5) and newer versions (6, 7, 8), providing faster generation and parsing. Includes a compatibility module, uuid_utils.compat, for frameworks like Django that require standard library uuid.UUID instances.

Tokens
2.5K
Snippets
7
Records
13
Agent score
63%

What's inside uuid-utils

  2. Ensure compatibility with frameworks like Django using uuid_utils.compat

    main

    Some frameworks (such as Django) require UUID instances to be from the standard-library uuid module rather than a custom subclass. If you encounter type-checking or compatibility issues, use uuid_utils.compat as a drop-in replacement. It returns standard library uuid.UUID instances while maintaining the performance benefits of the Rust implementation.

    import uuid_utils.compat as uuid

# This returns a standard library UUID instance
uuid.uuid4()

  3. Use uuid-utils for generating UUIDs

    main

    Import uuid_utils as uuid to access various UUID versions. This library supports standard versions (1, 3, 4, 5) as well as newer versions like 6, 7, and 8.

    Supported versions:

    • uuid1: Version 1 UUIDs using a timestamp and monotonic counter.
    • uuid3: Version 3 UUIDs based on the MD5 hash of some data.
    • uuid4: Version 4 UUIDs with random data.
    • uuid5: Version 5 UUIDs based on the SHA1 hash of some data.
    • uuid6: Version 6 UUIDs using a timestamp and monotonic counter.
    • uuid7: Version 7 UUIDs using a Unix timestamp ordered by time.
    • uuid8: Version 8 UUIDs using user-defined data.
    import uuid_utils as uuid

# make a random UUID
uuid.uuid4()

# make a random UUID using a Unix timestamp which is time-ordered.
uuid.uuid7()

# make a UUID using a SHA-1 hash of a namespace UUID and a name
uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')

# make a UUID using an MD5 hash of a namespace UUID and a name
uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')

  4. Properties of the uuid_utils.UUID class

    main

    The uuid_utils.UUID class provides several properties to access the UUID data in different formats and metadata:

    • bytes: 16-byte string in big-endian byte order.
    • bytes_le: 16-byte string with time_low, time_mid, and time_hi_version in little-endian byte order.
    • fields: A tuple of the six integer fields.
    • hex: 32-character hexadecimal string.
    • int: 128-bit integer representation.
    • urn: URN string as specified in RFC 4122.
    • variant: The UUID variant (e.g., RFC_4122).
    • version: The UUID version number.
    • is_safe: Enum indicating if the UUID was generated safely for multiprocessing (via uuid_generate_time_safe(3)).
    • timestamp: The timestamp in milliseconds since epoch. Note: This only works for UUID versions 1, 6, and 7; otherwise, it raises a ValueError.

  5. Generate random and custom UUIDs (v4, v8)

    main

    Use these functions for non-deterministic or custom UUID generation:

    • uuid4(): Generates a completely random UUID.
    • uuid8(a: int = None, b: int = None, c: int = None): Generates a UUID from three custom blocks:
      • a: First 48-bit chunk (octets 0-5).
      • b: Mid 12-bit chunk (octets 6-7).
      • c: Last 62-bit chunk (octets 8-15). If a value is not specified, a pseudo-random value is used for that block.

  6. Generate time-based UUIDs (v1, v6, v7)

    main

    Use these functions to generate UUIDs based on time and host information:

    • uuid1(node: int = None, clock_seq: int = None): Generates a UUID from a host ID, sequence number, and current time. If node is omitted, getnode() is used. If clock_seq is omitted, a random 14-bit sequence is used.
    • uuid6(node: int = None, clock_seq: int = None): Similar to uuid1 but reorders fields to improve database locality. It stores the 48 most significant bits of the timestamp first, followed by the version, then the remaining 12 bits.
    • uuid7(*, nanoseconds: int = None): Generates a UUID from a Unix timestamp in milliseconds and random bits. It features monotonicity within a millisecond. You can provide an explicit nanoseconds timestamp.

  7. Generate name-based UUIDs (v3, v5)

    main

    Generate deterministic UUIDs by hashing a namespace and a name:

    • uuid3(namespace: UUID, name: str | bytes): Uses the MD5 hash of the namespace UUID and the provided name.
    • uuid5(namespace: UUID, name: str | bytes): Uses the SHA-1 hash of the namespace UUID and the provided name.

    Both functions accept a name as either a string or bytes with no upper limit on length.

  8. Reference: uuid_utils module functions and constants

    main

    The uuid_utils module provides the following constants and utility functions:

    • NIL: The nil UUID (all 128 bits set to zero).
    • MAX: The max UUID (all 128 bits set to one).
    • getnode(): Returns the hardware address as a 48-bit positive integer.

  9. Access UUID properties and components

    main

    Once you have a UUID object, you can access its data through several properties:

    • hex: Returns the UUID as a simple hexadecimal string (without hyphens).
    • bytes: Returns the 16 bytes of the UUID.
    • bytes_le: Returns the 16 bytes in little-endian order.
    • int: Returns the 128-bit integer representation.
    • urn: Returns the UUID in URN format.
    • version: Returns the version number (e.g., 1, 4, 7) if the variant is RFC 4122; otherwise None.
    • variant: Returns a string describing the variant (RFC_4122, RESERVED_NCS, RESERVED_MICROSOFT, or RESERVED_FUTURE).
    • node: Returns the 48-bit node value.
    • time: Returns the timestamp (behavior varies by version, e.g., v6/v7 vs others).
    • timestamp: Returns the Unix timestamp in milliseconds (only for versions 1, 6, or 7).
    • fields: Returns a tuple of the internal UUID components: (time_low, time_mid, time_hi_version, clock_seq_hi_variant, clock_seq_low, node).
    u = uuid_utils.uuid4()
print(u.hex)      # '...'
print(u.int)      # 123456789...
print(u.version)  # 4

  10. Initialize a UUID object

    main

    The UUID class can be instantiated using the new() method, which supports multiple initialization strategies. You must provide exactly one of the following arguments:

    • hex: A hexadecimal string representation.
    • bytes: A bytes object (big-endian).
    • bytes_le: A bytes object (little-endian).
    • fields: A tuple of (time_low, time_mid, time_hi_version, clock_seq_hi_variant, clock_seq_low, node).
    • int: A 128-bit integer.

    Additionally, you can optionally provide a version argument (1-8) to set the UUID version immediately after creation.

    # Example: Creating from hex
uuid = UUID(hex='6ba7b810-9dad-11d1-80b4-00c04fd430c8')

# Example: Creating from an integer
uuid = UUID(int=123456789)

# Example: Creating from fields
# (time_low, time_mid, time_hi_version, clock_seq_hi_variant, clock_seq_low, node)
fields = (0x12345678, 0x9abc, 0xdef0, 0x12, 0x34, 0x56789abcde)
uuid = UUID(fields=fields)

  11. Generate UUID versions 1, 3, 4, 5, 6, 7, and 8

    main

    The library provides high-performance functions for generating various UUID versions:

    • uuid1(node=None, clock_seq=None): Generates a version 1 UUID (time-based). Optionally specify a 64-bit node or clock_seq.
    • uuid3(namespace, name): Generates a version 3 UUID (MD5 hash) using a namespace (a UUID object) and a name (string or bytes).
    • uuid4(): Generates a version 4 UUID (random).
    • uuid4_int(): Returns the version 4 UUID as a 128-bit integer.
    • uuid5(namespace, name): Generates a version 5 UUID (SHA-1 hash) using a namespace (a UUID object) and a name (string or bytes).
    • uuid6(node=None, clock_seq=None): Generates a version 6 UUID (reordered time-based).
    • uuid7(nanoseconds=None): Generates a version 7 UUID (Unix epoch time-based). Optionally specify nanoseconds as a 128-bit integer.
    • uuid7_int(nanoseconds=None): Returns the version 7 UUID as a 128-bit integer.
    • uuid8(a=None, b=None, c=None): Generates a version 8 UUID (custom) using three optional 64-bit integers a, b, and c.
    import uuid_utils

# Version 4
u4 = uuid_utils.uuid4()

# Version 5 (Name-based)
namespace = uuid_utils.NAMESPACE_DNS
u5 = uuid_utils.uuid5(namespace, "example.com")

# Version 7 (Time-based)
u7 = uuid_utils.uuid7()

# Version 8 (Custom)
u8 = uuid_utils.uuid8(a=1, b=2, c=3)

  12. Retrieve and reseed the node ID

    main

    The library manages a node ID used for time-based UUIDs (v1, v6).

    • getnode(): Returns the current 64-bit node ID. It attempts to retrieve the MAC address from the system; if unavailable, it generates a random node ID.
    • reseed(): Reseeds the random number generator used by the library.
    import uuid_utils

node = uuid_utils.getnode()
print(f"Current node: {node}")

uuid_utils.reseed()