# 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 IETF draft][draft repository].
## Install
```shell
pip install uuid6
```
## Usage
```python
from uuid6 import uuid6, uuid7, uuid8
my_uuid = uuid6()
print(my_uuid)
assert my_uuid < uuid6()
my_uuid = uuid7()
print(my_uuid)
assert my_uuid < uuid7()
my_uuid = uuid8()
print(my_uuid)
assert my_uuid < uuid8()
```
## 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.
## 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 | time_low_and_version |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|clk_seq_hi_res | clk_seq_low | node (0-1) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| node (2-5) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
## 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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
## 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 |
+-----------+--------+-----------------------+-----------------------+-----------------------+-----------------------+
```
[draft repository]: https://github.com/ietf-wg-uuidrev/rfc4122bis
[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": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "uuid,uuid6,uuid7,uuid8,uuidv6,uuidv7,uuidv8",
"author": "Oittaa",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/77/9d/3b60bc68fa105d0757389afd1937b9c15dc0f35351f2eded1da33c78d39a/uuid6-2023.4.25.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 IETF draft][draft repository].\n\n## Install\n\n```shell\npip install uuid6\n```\n\n## Usage\n\n```python\nfrom uuid6 import uuid6, uuid7, uuid8\n\nmy_uuid = uuid6()\nprint(my_uuid)\nassert my_uuid < uuid6()\n\nmy_uuid = uuid7()\nprint(my_uuid)\nassert my_uuid < uuid7()\n\nmy_uuid = uuid8()\nprint(my_uuid)\nassert my_uuid < uuid8()\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## 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 | time_low_and_version |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n |clk_seq_hi_res | clk_seq_low | node (0-1) |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n | node (2-5) |\n +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n```\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## 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[draft repository]: https://github.com/ietf-wg-uuidrev/rfc4122bis\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": "",
"summary": "New time-based UUID formats which are suited for use as a database key",
"version": "2023.4.25",
"split_keywords": [
"uuid",
"uuid6",
"uuid7",
"uuid8",
"uuidv6",
"uuidv7",
"uuidv8"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f111f51a953e60774eb459ab1ac0d391eaaa7ed211fb4f4e1c45cb6528096281",
"md5": "d3cac339d2005a2c8fb27bda82e4d09a",
"sha256": "b6c717c388868d97e6722d5f9f37f6a57af2f4ae2a23f13a0572a52ac447c2f1"
},
"downloads": -1,
"filename": "uuid6-2023.4.25-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3cac339d2005a2c8fb27bda82e4d09a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5739,
"upload_time": "2023-04-25T10:04:12",
"upload_time_iso_8601": "2023-04-25T10:04:12.061453Z",
"url": "https://files.pythonhosted.org/packages/f1/11/f51a953e60774eb459ab1ac0d391eaaa7ed211fb4f4e1c45cb6528096281/uuid6-2023.4.25-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "779d3b60bc68fa105d0757389afd1937b9c15dc0f35351f2eded1da33c78d39a",
"md5": "9982076301ff25196d2902e3b8f3ef77",
"sha256": "db5f2de1ab7b6c96926860d7000801d194d65a13a2b5b574895eb19b35d81fcf"
},
"downloads": -1,
"filename": "uuid6-2023.4.25.tar.gz",
"has_sig": false,
"md5_digest": "9982076301ff25196d2902e3b8f3ef77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8097,
"upload_time": "2023-04-25T10:04:13",
"upload_time_iso_8601": "2023-04-25T10:04:13.764953Z",
"url": "https://files.pythonhosted.org/packages/77/9d/3b60bc68fa105d0757389afd1937b9c15dc0f35351f2eded1da33c78d39a/uuid6-2023.4.25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-25 10:04:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "oittaa",
"github_project": "uuid6-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "uuid6"
}
JSON
