Metadata-Version: 2.1
Name: uuid-v9
Version: 0.0.4
Summary: The v9 UUID supports both time-based sequential and random non-sequential IDs with an optional prefix, an optional checksum, and sufficient randomness to avoid collisions.
Author: JHunt
Author-email: hello@jhunt.dev
Platform: any
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# UUID v9

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.

<!-- To learn more about UUID v9, please visit the website: https://uuid-v9.jhunt.dev -->

## Installation

Install UUID v9 from PyPI.

```bash
python3 -m pip install uuid-v9
```

## Usage

```python
from uuid_v9 import uuid, is_valid_uuid

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

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

### Command Line Usage

```bash
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 will not accept some v9 UUIDs. 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](LICENSE).
