# uuid6
New time-based UUID formats which are suited for use as a database key.
[](https://github.com/oittaa/uuid6-python/actions/workflows/main.yml)
[](https://codecov.io/gh/oittaa/uuid6-python)
[](https://pypi.org/project/uuid6/)
[](https://pypi.org/project/uuid6/)
[](https://github.com/psf/black)
This module extends immutable UUID objects (the UUID class) with the functions `uuid6()`, `uuid7()`, and `uuid8()` from the proposed [IETF RFC 9562][rfc9562].
## Install
```shell
pip install uuid6
```
## Usage
```python
import uuid6
my_uuid = uuid6.uuid6()
print(my_uuid)
assert my_uuid < uuid6.uuid6()
my_uuid = uuid6.uuid7()
print(my_uuid)
assert my_uuid < uuid6.uuid7()
my_uuid = uuid6.uuid8()
print(my_uuid)
assert my_uuid < uuid6.uuid8()
import uuid
my_uuid = uuid.UUID(hex="C232AB00-9414-11EC-B3C8-9E6BDECED846")
assert uuid6.uuid1_to_uuid6(my_uuid) == uuid.UUID(hex="1EC9414C-232A-6B00-B3C8-9E6BDECED846")
```
## Which UUID version should I use?
> Implementations SHOULD utilize UUID version 7 over UUID version 1 and 6 if possible.
UUID version 7 features a time-ordered value field derived from the widely implemented and well known Unix Epoch timestamp source, the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded. As well as improved entropy characteristics over versions 1 or 6.
If your use case requires greater granularity than UUID version 7 can provide, you might consider UUID version 8. UUID version 8 doesn't provide as good entropy characteristics as UUID version 7, but it utilizes timestamp with nanosecond level of precision.
## Functions
### uuid6.uuid1_to_uuid6(*uuid1*)
Generate a UUID version 6 object from a UUID version 1 object.
### uuid6.uuid6(*node=None*, *clock_seq=None*)
Generate a UUID from a host ID, sequence number, and the current time. If *node* is not given, a random 48-bit number is chosen. If *clock_seq* is given, it is used as the sequence number; otherwise a random 14-bit sequence number is chosen.
### uuid6.uuid7()
Generate a UUID from a random number, and the current time.
### uuid6.uuid8()
Generate a UUID from a random number, and the current time.
## UUID Version 6
UUID version 6 is a field-compatible version of UUIDv1, reordered for improved DB locality. It is expected that UUIDv6 will primarily be used in contexts where there are existing v1 UUIDs. Systems that do not involve legacy UUIDv1 **SHOULD** use UUIDv7 instead.
### UUIDv6 Field and Bit 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| time_high |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| time_mid | ver | time_low |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var| clock_seq | node |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| node |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
## UUID Version 7
UUID version 7 features a time-ordered value field derived from the widely implemented and well known Unix Epoch timestamp source, the number of milliseconds seconds since midnight 1 Jan 1970 UTC, leap seconds excluded. UUID version 7 also has improved entropy characteristics over versions 1 or 6.
### UUIDv7 Field and Bit 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| unix_ts_ms |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| unix_ts_ms | ver | rand_a |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var| rand_b |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| rand_b |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
## UUID Version 8
UUID version 8 provides an RFC-compatible format for experimental or vendor-specific use cases.
This implementation of `uuid8()` sacrifices some entropy for granularity compared to `uuid7()`, while being otherwise compatible.
### UUIDv8 Field and Bit 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| unix_ts_ms |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| unix_ts_ms | ver | subsec_a |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var| subsec_b | rand |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| rand |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
- `unix_ts_ms`: 48 bit big-endian unsigned number of Unix epoch timestamp with millisecond level of precision
- `ver`: The 4 bit UUIDv8 version (1000)
- `subsec_a`: 12 bits allocated to sub-second precision values
- `var`: 2 bit UUID variant (10)
- `subsec_b`: 8 bits allocated to sub-second precision values
- `rand`: The remaining 54 bits are filled with [cryptographically strong random data][python randbits]
20 extra bits dedicated to sub-second precision provide nanosecond resolution. The `unix_ts_ms`, `subsec_a`, and `subsec_b` fields guarantee the order of UUIDs generated within the same nanosecond by monotonically incrementing the timer.
## Performance
Run the shell script [bench.sh][bench] to test on your own machine.
### Results
MacBook Air 2020
```
Python 3.10.4
Mean +- std dev: 870 ns +- 11 ns
Mean +- std dev: 1.17 us +- 0.01 us
Mean +- std dev: 2.18 us +- 0.02 us
Mean +- std dev: 1.60 us +- 0.02 us
Mean +- std dev: 1.78 us +- 0.02 us
+-----------+--------+-----------------------+-----------------------+-----------------------+-----------------------+
| Benchmark | uuid1 | uuid4 | uuid6 | uuid7 | uuid8 |
+===========+========+=======================+=======================+=======================+=======================+
| timeit | 870 ns | 1.17 us: 1.35x slower | 2.18 us: 2.51x slower | 1.60 us: 1.84x slower | 1.78 us: 2.04x slower |
+-----------+--------+-----------------------+-----------------------+-----------------------+-----------------------+
```
[rfc9562]: https://datatracker.ietf.org/doc/rfc9562/
[python randbits]: https://docs.python.org/3/library/secrets.html#secrets.randbits
[bench]: https://github.com/oittaa/uuid6-python/blob/main/bench.sh
Raw data
{
"_id": null,
"home_page": "https://github.com/oittaa/uuid6-python",
"name": "uuid6",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "uuid, uuid6, uuid7, uuid8, uuidv6, uuidv7, uuidv8",
"author": "Oittaa",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2c/56/2560a9f1ccab9e12b1b3478a3c870796cf4d8ee5652bb19b61751cced14a/uuid6-2024.7.10.tar.gz",
"platform": null,
"description": "# uuid6\nNew time-based UUID formats which are suited for use as a database key.\n\n[](https://github.com/oittaa/uuid6-python/actions/workflows/main.yml)\n[](https://codecov.io/gh/oittaa/uuid6-python)\n[](https://pypi.org/project/uuid6/)\n[](https://pypi.org/project/uuid6/)\n[](https://github.com/psf/black)\n\nThis module extends immutable UUID objects (the UUID class) with the functions `uuid6()`, `uuid7()`, and `uuid8()` from the proposed [IETF RFC 9562][rfc9562].\n\n## Install\n\n```shell\npip install uuid6\n```\n\n## Usage\n\n```python\nimport uuid6\n\nmy_uuid = uuid6.uuid6()\nprint(my_uuid)\nassert my_uuid < uuid6.uuid6()\n\nmy_uuid = uuid6.uuid7()\nprint(my_uuid)\nassert my_uuid < uuid6.uuid7()\n\nmy_uuid = uuid6.uuid8()\nprint(my_uuid)\nassert my_uuid < uuid6.uuid8()\n\nimport uuid\n\nmy_uuid = uuid.UUID(hex=\"C232AB00-9414-11EC-B3C8-9E6BDECED846\")\nassert uuid6.uuid1_to_uuid6(my_uuid) == uuid.UUID(hex=\"1EC9414C-232A-6B00-B3C8-9E6BDECED846\")\n```\n\n## Which UUID version should I use?\n\n> Implementations SHOULD utilize UUID version 7 over UUID version 1 and 6 if possible.\n\nUUID version 7 features a time-ordered value field derived from the widely implemented and well known Unix Epoch timestamp source, the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded. As well as improved entropy characteristics over versions 1 or 6.\n\nIf your use case requires greater granularity than UUID version 7 can provide, you might consider UUID version 8. UUID version 8 doesn't provide as good entropy characteristics as UUID version 7, but it utilizes timestamp with nanosecond level of precision.\n\n## Functions\n\n### uuid6.uuid1_to_uuid6(*uuid1*)\n\nGenerate a UUID version 6 object from a UUID version 1 object.\n\n### uuid6.uuid6(*node=None*, *clock_seq=None*)\n\nGenerate a UUID from a host ID, sequence number, and the current time. If *node* is not given, a random 48-bit number is chosen. If *clock_seq* is given, it is used as the sequence number; otherwise a random 14-bit sequence number is chosen.\n\n### uuid6.uuid7()\n\nGenerate a UUID from a random number, and the current time.\n\n### uuid6.uuid8()\n\nGenerate a UUID from a random number, and the current time.\n\n## UUID Version 6\n\nUUID version 6 is a field-compatible version of UUIDv1, reordered for improved DB locality. It is expected that UUIDv6 will primarily be used in contexts where there are existing v1 UUIDs. Systems that do not involve legacy UUIDv1 **SHOULD** use UUIDv7 instead.\n\n### UUIDv6 Field and Bit Layout\n\n```\n 0 1 2 3\n 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\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | time_high |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | time_mid | ver | time_low |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n |var| clock_seq | node |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | node |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n```\n\n## UUID Version 7\n\nUUID version 7 features a time-ordered value field derived from the widely implemented and well known Unix Epoch timestamp source, the number of milliseconds seconds since midnight 1 Jan 1970 UTC, leap seconds excluded. UUID version 7 also has improved entropy characteristics over versions 1 or 6.\n\n### UUIDv7 Field and Bit Layout\n\n```\n 0 1 2 3\n 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\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | unix_ts_ms |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | unix_ts_ms | ver | rand_a |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n |var| rand_b |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | rand_b |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n```\n\n## UUID Version 8\n\nUUID version 8 provides an RFC-compatible format for experimental or vendor-specific use cases.\n\nThis implementation of `uuid8()` sacrifices some entropy for granularity compared to `uuid7()`, while being otherwise compatible.\n\n### UUIDv8 Field and Bit Layout\n\n```\n 0 1 2 3\n 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\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | unix_ts_ms |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | unix_ts_ms | ver | subsec_a |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n |var| subsec_b | rand |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | rand |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n```\n\n- `unix_ts_ms`: 48 bit big-endian unsigned number of Unix epoch timestamp with millisecond level of precision\n- `ver`: The 4 bit UUIDv8 version (1000)\n- `subsec_a`: 12 bits allocated to sub-second precision values\n- `var`: 2 bit UUID variant (10)\n- `subsec_b`: 8 bits allocated to sub-second precision values\n- `rand`: The remaining 54 bits are filled with [cryptographically strong random data][python randbits]\n\n 20 extra bits dedicated to sub-second precision provide nanosecond resolution. The `unix_ts_ms`, `subsec_a`, and `subsec_b` fields guarantee the order of UUIDs generated within the same nanosecond by monotonically incrementing the timer.\n\n## Performance\n\nRun the shell script [bench.sh][bench] to test on your own machine.\n\n### Results\n\nMacBook Air 2020\n```\nPython 3.10.4\nMean +- std dev: 870 ns +- 11 ns\nMean +- std dev: 1.17 us +- 0.01 us\nMean +- std dev: 2.18 us +- 0.02 us\nMean +- std dev: 1.60 us +- 0.02 us\nMean +- std dev: 1.78 us +- 0.02 us\n+-----------+--------+-----------------------+-----------------------+-----------------------+-----------------------+\n| Benchmark | uuid1 | uuid4 | uuid6 | uuid7 | uuid8 |\n+===========+========+=======================+=======================+=======================+=======================+\n| timeit | 870 ns | 1.17 us: 1.35x slower | 2.18 us: 2.51x slower | 1.60 us: 1.84x slower | 1.78 us: 2.04x slower |\n+-----------+--------+-----------------------+-----------------------+-----------------------+-----------------------+\n```\n\n[rfc9562]: https://datatracker.ietf.org/doc/rfc9562/\n[python randbits]: https://docs.python.org/3/library/secrets.html#secrets.randbits\n[bench]: https://github.com/oittaa/uuid6-python/blob/main/bench.sh\n",
"bugtrack_url": null,
"license": null,
"summary": "New time-based UUID formats which are suited for use as a database key",
"version": "2024.7.10",
"project_urls": {
"Homepage": "https://github.com/oittaa/uuid6-python"
},
"split_keywords": [
"uuid",
" uuid6",
" uuid7",
" uuid8",
" uuidv6",
" uuidv7",
" uuidv8"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d33e4ae6af487ce5781ed71d5fe10aca72e7cbc4d4f45afc31b120287082a8dd",
"md5": "9dd2420de73a99406113ceef7ea88463",
"sha256": "93432c00ba403751f722829ad21759ff9db051dea140bf81493271e8e4dd18b7"
},
"downloads": -1,
"filename": "uuid6-2024.7.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9dd2420de73a99406113ceef7ea88463",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6376,
"upload_time": "2024-07-10T16:39:36",
"upload_time_iso_8601": "2024-07-10T16:39:36.148969Z",
"url": "https://files.pythonhosted.org/packages/d3/3e/4ae6af487ce5781ed71d5fe10aca72e7cbc4d4f45afc31b120287082a8dd/uuid6-2024.7.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2c562560a9f1ccab9e12b1b3478a3c870796cf4d8ee5652bb19b61751cced14a",
"md5": "7288afe9f6e5ee4366a9367cb061cb42",
"sha256": "2d29d7f63f593caaeea0e0d0dd0ad8129c9c663b29e19bdf882e864bedf18fb0"
},
"downloads": -1,
"filename": "uuid6-2024.7.10.tar.gz",
"has_sig": false,
"md5_digest": "7288afe9f6e5ee4366a9367cb061cb42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8705,
"upload_time": "2024-07-10T16:39:37",
"upload_time_iso_8601": "2024-07-10T16:39:37.592488Z",
"url": "https://files.pythonhosted.org/packages/2c/56/2560a9f1ccab9e12b1b3478a3c870796cf4d8ee5652bb19b61751cced14a/uuid6-2024.7.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-10 16:39:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oittaa",
"github_project": "uuid6-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "uuid6"
}
JSON
