Skip to main content

New time-based UUID formats which are suited for use as a database key

Project description

uuid6

New time-based UUID formats which are suited for use as a database key.

CI codecov PyPI status Python versions supported Code style: black

This module extends immutable UUID objects (the UUID class) with the functions uuid6() and uuid7() from the IETF draft.

Install

pip install uuid6

Usage

from uuid6 import uuid6, uuid7

my_uuid = uuid6()
print(my_uuid)
assert my_uuid < uuid6()

my_uuid = uuid7()
print(my_uuid)
assert my_uuid < uuid7()

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

Draft 02

        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
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                            unixts                             |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |unixts |       subsec_a        |  ver  |       subsec_b        |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |var|                   subsec_seq_node                         |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                       subsec_seq_node                         |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

This implementation

        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
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                            unixts                             |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |unixts |       subsec_a        |  ver  |       subsec_b        |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |var| subsec_c  |             rand                              |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                             rand                              |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  • unixts: 36 bit big-endian unsigned Unix Timestamp value
  • subsec_a: 12 bits allocated to sub-second precision values
  • ver: The 4 bit UUIDv7 version (0111)
  • subsec_b: 12 bits allocated to sub-second precision values
  • var: 2 bit UUID variant (10)
  • subsec_c: 6 bits allocated to sub-second precision values
  • rand: The remaining 56 bits are filled with pseudo-random data

30 bits dedicated to sub-second precision provide nanosecond resolution. The unixts and subsec fields guarantee the order of UUIDs generated within the same nanosecond by monotonically incrementing the timer.

This implementation does not include a clock sequence counter as defined in the draft RFC.

Performance

MacBook Air

Python 3.9.7 (default, Oct 12 2021, 22:38:23)
[Clang 13.0.0 (clang-1300.0.29.3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import timeit
>>> timeit.timeit('uuid1()', number=100000, setup="from uuid import uuid1")
0.14462158300011652
>>> timeit.timeit('uuid6()', number=100000, setup="from uuid6 import uuid6")
0.2687861250000019
>>> timeit.timeit('uuid7()', number=100000, setup="from uuid6 import uuid7")
0.22819437500000106

Google Cloud Shell VM

Python 3.7.3 (default, Jan 22 2021, 20:04:44)
[GCC 8.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import timeit
>>> timeit.timeit('uuid1()', number=100000, setup="from uuid import uuid1")
1.2075679750000745
>>> timeit.timeit('uuid6()', number=100000, setup="from uuid6 import uuid6")
0.6328954440000416
>>> timeit.timeit('uuid7()', number=100000, setup="from uuid6 import uuid7")
0.4709622599998511

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

uuid6-2021.12.1.tar.gz (6.4 kB view details)

Uploaded Source

Built Distribution

uuid6-2021.12.1-py3-none-any.whl (5.1 kB view details)

Uploaded Python 3

File details

Details for the file uuid6-2021.12.1.tar.gz.

File metadata

  • Download URL: uuid6-2021.12.1.tar.gz
  • Upload date:
  • Size: 6.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

File hashes

Hashes for uuid6-2021.12.1.tar.gz
Algorithm Hash digest
SHA256 341b2823a3455d5a3773d672abba1ee353529444346fd11c8e309763a3651d57
MD5 b970d4eb471ca43ff032bc27e0fb4452
BLAKE2b-256 f5eea624bae93f3d22ad1a0179e641de34994574f2ae40c3ab2179bf5abcbcc8

See more details on using hashes here.

File details

Details for the file uuid6-2021.12.1-py3-none-any.whl.

File metadata

  • Download URL: uuid6-2021.12.1-py3-none-any.whl
  • Upload date:
  • Size: 5.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

File hashes

Hashes for uuid6-2021.12.1-py3-none-any.whl
Algorithm Hash digest
SHA256 a0a5131c3880137dac1948ae94e30ddfb0824d7e9fefd54279e146e8b08fa1cf
MD5 1e2a3d4ad679e06f9883b08b7493fd0a
BLAKE2b-256 585ce0d7b9b0ed36576a2d7f8beef19589b8f41b3bced33745e09ace307a25dc

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page