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

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()``, ``uuid7()``, and ``uuid8()`` from the proposed [IETF RFC 9562][rfc9562]. Install ------- .. code:: shell pip install uuid6 Usage ----- .. code:: 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") Versioning ========== **Important Notice:** Starting with version ``2025.0.0``, this project will transition from Calendar Versioning (YYYY.MM.DD) to Semantic Versioning (MAJOR.MINOR.PATCH). Version Scheme ~~~~~~~~~~~~~~ - **Before 2025.0.0**: Calendar Versioning (e.g., ``2024.07.10``) - **2025.0.0 and after**: Semantic Versioning where: - **MAJOR**: Breaking changes - **MINOR**: New features (backward compatible) - **PATCH**: Bug fixes (backward compatible) For Dependency Management ~~~~~~~~~~~~~~~~~~~~~~~~~ - Requirements like ``>=2024.07.10`` will continue to work with newer versions - For the latest features, specify ``>=2025.0.0`` Release Process ~~~~~~~~~~~~~~~ Version numbers are managed automatically via Git tags. 1. Maintainers create a new tag following the version scheme: .. code:: bash git tag <version> git tag 2025.0.0 # First SemVer release git tag 2025.1.0 # Feature release git tag 2025.0.1 # Bug fix release 2. Push the tag to GitHub .. code:: bash git push origin <version> 3. GitHub Actions will build and publish the package to PyPI 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. This function is *not* thread-safe. uuid6.uuid7() ~~~~~~~~~~~~~ Generate a UUID from a random number, and the current time. This function is *not* thread-safe. uuid6.uuid8() ~~~~~~~~~~~~~ Generate a UUID from a random number, and the current time. This function is *not* thread-safe. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The ``time_high``, ``time_mid``, and ``time_low`` fields guarantee the order of UUIDs generated within the same timestamp by monotonically incrementing the time .. |CI| image:: https://github.com/oittaa/uuid6-python/actions/workflows/main.yml/badge.svg :target: https://github.com/oittaa/uuid6-python/actions/workflows/main.yml .. |codecov| image:: https://codecov.io/gh/oittaa/uuid6-python/branch/main/graph/badge.svg?token=O59DZ6UWQV :target: https://codecov.io/gh/oittaa/uuid6-python .. |PyPI status| image:: https://badge.fury.io/py/uuid6.svg :target: https://pypi.org/project/uuid6/ .. |Python versions supported| image:: https://img.shields.io/pypi/pyversions/uuid6.svg?logo=python :target: https://pypi.org/project/uuid6/ .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black