Metadata-Version: 2.4
Name: uuidv8
Version: 1.0.0
Summary: Generate UUID version 8 identifiers as defined in RFC 9562 — custom-use UUIDs with cryptographically random fields
Project-URL: Homepage, https://github.com/shubham151/uuidv8-python#readme
Project-URL: Repository, https://github.com/shubham151/uuidv8-python
Project-URL: Bug Tracker, https://github.com/shubham151/uuidv8-python/issues
Author: Shubham Mishra
License: GPL-3.0
License-File: LICENSE
Keywords: guid,rfc9562,unique,uuid,uuidv8
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# uuidv8

Generate **UUID version 8** identifiers as defined in [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562).

```
f6440f3e-14a2-8293-add2-1066de13086a
         ^^^^                          ← version = 8
                   ^                  ← variant = 10xx
```

No dependencies. Uses only the Python standard library (`secrets`).

---

## What is UUID v8?

UUID v8 is a **custom-use UUID format** introduced in RFC 9562 alongside the more widely known v7. Where v7 is opinionated (millisecond timestamp + random bits), **v8 leaves 122 of its 128 bits entirely up to you**.

The spec only mandates two things:

| Bits  | Field   | Value      |
|-------|---------|------------|
| 48–51 | version | `1000` (= 8) |
| 64–65 | variant | `10`       |

Everything else — the remaining 122 bits split across `custom_a`, `custom_b`, and `custom_c` — is yours to define.

This package fills all custom fields with cryptographically random bytes, making it a drop-in for any situation where you need a universally unique, opaque identifier and none of the earlier UUID versions quite fit.

---

## When to use UUID v8

| Situation | Good fit? |
|-----------|-----------|
| You need a random, unique ID with no embedded meaning | Yes — same collision resistance as v4 |
| You want a UUID that signals "custom / vendor-specific" to readers of your schema | Yes — the `8` version nibble is a clear marker |
| You are building a proprietary UUID layout (e.g. embedding a shard ID or timestamp in your own format) | Yes — swap in your own bits instead of random ones |
| You need time-sortable IDs | No — use UUID v7 |
| You need backwards compatibility with systems that only accept v4 | No — use UUID v4 |

---

## Installation

```bash
pip install uuidv8
```

Requires Python 3.8 or later. No third-party dependencies.

---

## Usage

```python
from uuidv8 import uuidv8, validate

uid = uuidv8()
print(uid)            # "f6440f3e-14a2-8293-add2-1066de13086a"
print(validate(uid))  # True
```

---

## API

### `uuidv8() -> str`

Returns a new UUID v8 string with cryptographically random custom fields.

```python
uuidv8()  # "a1b2c3d4-e5f6-8abc-9def-0123456789ab"
```

The returned string is always lowercase and follows the standard 8-4-4-4-12 hyphenated format.

### `validate(uuid: object) -> bool`

Returns `True` if the given value is a valid UUID v8 (correct format, version nibble = `8`, variant bits = `10xx`). Returns `False` for anything else, including other UUID versions.

```python
validate("a1b2c3d4-e5f6-8abc-9def-0123456789ab")  # True  — valid v8
validate("f47ac10b-58cc-4372-a567-0e02b2c3d479")  # False — this is v4
validate("not-a-uuid")                             # False
validate(None)                                     # False
```

---

## UUID v8 layout

```
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                          custom_a                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           custom_a            |  ver  |       custom_b        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                       custom_c                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           custom_c                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```

| Field      | Bits | Value (this package) |
|------------|------|----------------------|
| `custom_a` | 48   | random               |
| `ver`      | 4    | `8`                  |
| `custom_b` | 12   | random               |
| `var`      | 2    | `10`                 |
| `custom_c` | 62   | random               |

---

## License

[GPL-3.0](./LICENSE)
