UUID7 Standard (pypi: uuid7-standard)

Common errors

• ModuleNotFoundError: No module named 'uuid7'

  cause This error typically occurs when you've installed `uuid7-standard` but are attempting to import from `uuid7` (e.g., `import uuid7`). The `uuid7` package is a separate, distinct library.
  fix If you intend to use the `uuid7-standard` library, ensure your imports are `from uuid7_standard import ...`. If you genuinely meant to use the other package, install it via `pip install uuid7`.

• AttributeError: module 'uuid7_standard' has no attribute 'uuid7'

  cause You are likely trying to call a function or attribute (like `uuid7.uuid7()` or `uuid7.generate()`) that exists in the *other* `uuid7` package, but not in `uuid7_standard`.
  fix Use the correct API for `uuid7-standard`. The main generation function is `generate_uuid()` (e.g., `from uuid7_standard import generate_uuid; new_uuid = generate_uuid()`).

• ValueError: bad badly formed hexadecimal UUID string

  cause This error occurs when attempting to create a `UUID7` object from a string that is not a valid UUID format (e.g., incorrect length, invalid characters, or missing hyphens).
  fix Ensure the input string conforms to the UUID standard, which is a 32-character hexadecimal string, optionally separated by hyphens (e.g., `UUID7('018d9f0a-b2c3-7a4e-9f0d-1e2f3g4h5i6j')`).

Warnings

• gotcha There is a significant potential for confusion with the `uuid7` package on PyPI. The `uuid7` package implements an older draft of the UUIDv7 standard, which is different from the final standard implemented by `uuid7-standard`.
  Fix: Always explicitly install `pip install uuid7-standard` and import from `uuid7_standard` (e.g., `from uuid7_standard import generate_uuid`) to ensure you are using the final standard's implementation. Do not use `import uuid7` if you intend to use this library.
• gotcha The `generate_uuid()` function returns a `UUID7` object, which provides methods for accessing its components (like `datetime`). It does not directly return a string. If a string representation is immediately needed, explicit conversion is required.
  Fix: To obtain the UUID string, explicitly cast the `UUID7` object to `str()` (e.g., `str(generate_uuid())`) or use its `.hex` attribute (e.g., `generate_uuid().hex`).

Install

• pip install uuid7-standard Install uuid7-standard

Imports

• generate_uuid
  wrong:

  import uuid7

  correct:

  from uuid7_standard import generate_uuid

  The `import uuid7` statement imports a *different* package (`uuid7`) based on an older draft of the UUIDv7 standard. For the final standard, ensure you install `uuid7-standard` and import from `uuid7_standard`.
• UUID7
  wrong:

  from uuid7 import UUID7

  correct:

  from uuid7_standard import UUID7

  Similar to `generate_uuid`, importing `UUID7` from the `uuid7` package will use a different implementation based on an older draft.

Quickstart

This quickstart demonstrates how to generate a new UUIDv7 using `generate_uuid()` and how to parse an existing UUIDv7 string back into a `UUID7` object.

from uuid7_standard import generate_uuid, UUID7

# Generate a UUIDv7 object
new_uuid = generate_uuid()
print(f"Generated UUIDv7 object: {new_uuid}")
print(f"Type: {type(new_uuid)}")
print(f"UUIDv7 as string: {str(new_uuid)}")

# You can also parse a UUIDv7 string into a UUID7 object
# Example valid UUIDv7 string (replace with your actual UUID if needed)
uuid_str = str(new_uuid) # Or use a known valid UUIDv7 string
try:
    parsed_uuid = UUID7(uuid_str)
    print(f"Parsed UUIDv7 object: {parsed_uuid}")
    print(f"Timestamp of parsed UUID: {parsed_uuid.datetime}")
except ValueError as e:
    print(f"Error parsing UUID: {e}")