uuid-v9 0.1.1

Fast, lightweight, and dependency-free implementation of the UUID version 9 proposal for Python.

UUID v9

Fast, lightweight, and dependency-free implementation of the UUID version 9 proposal for Python.

The v9 UUID supports both time-based sequential and random non-sequential UUIDs with an optional prefix, an optional checksum, and sufficient randomness to avoid collisions. It uses the UNIX timestamp for sequential UUIDs and CRC-8 for checksums. A version digit can be added if desired, but is omitted by default.

Installation

Install UUID v9 from PyPI.

python3 -m pip install uuid-v9

Usage

from uuid_v9 import uuidv9, is_valid_uuidv9

ordered_id = uuidv9()
prefixed_ordered_id = uuidv9('a1b2c3d4') # up to 8 hexadecimal characters
unordered_id = uuidv9('', False)
prefixed_unordered_id = uuidv9('a1b2c3d4', False)
ordered_id_with_checksum = uuidv9('', True, True)
ordered_id_with_version = uuidv9('', True, True, True)
ordered_id_with_compatibility = uuidv9('', True, False, False, True)

const is_valid = validate_uuidv9(ordered_id) # build-in UUID validator
const is_valid_with_checksum = validate_uuidv9(ordered_id_with_checksum, True)
const is_valid_with_version = validate_uuidv9(ordered_id_with_version, True, True)
const is_valid_with_compatibility = validate_uuidv9(ordered_id_with_compatibility, True, '1')

Command Line Usage

python3 uuid_v9.py
python3 uuid_v9.py --prefix 'a1b2c3d4' # add a prefix
python3 uuid_v9.py --unordered # omit the timestamp
python3 uuid_v9.py --checksum # add a CRC-8 checksum
python3 uuid_v9.py --version # add a version 9 digit
python3 uuid_v9.py --backcompat # compatibility mode (see below)

Compatibility

Some UUID validators check for specific features of v1 or v4 UUIDs. This causes some valid v9 UUIDs to appear invalid. Three possible workarounds are:

1. Use the built-in validator (recommended)
2. Use compatibility mode*
3. Bypass the validator (not recommended)

*Compatibility mode adds version and variant digits to immitate v1 or v4 UUIDs based on whether or not you have a timestamp.

Format

Here is the UUID v9 format: xxxxxxxx-xxxx-9xxx-8xxx-xxxxxxxxxxyy

x = prefix/timestamp/random, y = checksum (optional), 9 = version (optional), 8 = variant (compatibility mode)

License

This project is licensed under the MIT License.