diff --git a/README.md b/README.md index f16ca38..888cd35 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ # UUIDv7 for Python -A simple module for generating UUIDv7 that contain creation -timestamps. Another function for extracting the time of an UUID. +A simple module for generating UUIDv7 that contain creation timestamps. Another function for extracting the time of an UUID. -Note: As of writing, Python has no UUIDv7 support. There's an abandoned package `uuid7` that uses a draft RFC with incorrect timestamps (some two centuries off). These modules conflict, uninstall the other one. +ℹ️ As of writing, Python had no UUIDv7 support. Now it does, but doesn't allow providing nor extracting timestamps, which both are supported by this module. Beware there's also an abandoned package `uuid7` that uses a draft RFC with incorrect timestamps (some two centuries off). - **Standard compliant**: Follows the final UUIDv7 [specification](https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7). - **Pythonic**: Uses stdlib `datetime` and `UUID` facilities rather than milliseconds or bare strings. @@ -15,6 +14,7 @@ pip install uuid7-standard ``` Or for your project using [uv](https://docs.astral.sh/uv/): + ```sh uv add uuid7-standard ``` @@ -24,7 +24,7 @@ uv add uuid7-standard ```python import uuid7 -# Create a random UUIDv7 with current timestamp +# Create a random UUIDv7 with current timestamp, same as uuid.uuid7() u = uuid7.create() print(str(u), u.bytes) @@ -41,12 +41,16 @@ u = UUID('00000000-0000-7dac-b3e3-ecb571bb3e2f') timestamp = uuid7.time(u) # 1970-01-01 UTC ``` -### `create(when: datetime?) -> UUID` +### `uuid7.create(when: datetime?) -> UUID` Create a UUIDv7 with timestamp-based ordering. The current time is used, unless `when` is passed as datetime (local time or timezone-aware) This is useful e.g. for creating a bunch of UUIDv7 with precisely the same timestamp. -### `time(u: UUID|str) -> datetime` +### `uuid7.time(u: UUID|str) -> datetime` Extract the timestamp from a UUIDv7. Raises ValueError if the UUID is not a UUIDv7. + +### `uuid7.UUID` re-export of stdlib UUID + +In case you wish to explicitly indicate in your code that something is supposed to be v7, and avoid `import uuid`. Note that it **is** `uuid.UUID`, and does not actually enforce v7 format. This is useful with humans and coding agents, to avoid them accidentally using `uuid4()` when dealing with it. diff --git a/pyproject.toml b/pyproject.toml index 6cade56..04dac40 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uuid7-standard" -version = "1.1.0" +version = "1.1.1" description = "UUIDv7 with the final standard. Not to be confused with the uuid7 package on pypi, based on a draft version that was very different." readme = "README.md" requires-python = ">=3.8" @@ -20,8 +20,8 @@ classifiers = [ ] [project.urls] -Homepage = "https://git.zi.fi/LeoVasanko/uuid7-standard" -Repository = "https://github.com/LeoVasanko/uuid7-standard" +Repository = "https://git.zi.fi/LeoVasanko/uuid7-standard" +Issues = "https://github.com/LeoVasanko/uuid7-standard" [build-system] requires = ["hatchling"] diff --git a/uuid7.py b/uuid7.py index 531b599..edcbc9a 100644 --- a/uuid7.py +++ b/uuid7.py @@ -4,7 +4,7 @@ from datetime import timezone as _tz from secrets import token_bytes as _token_bytes from uuid import UUID -__all__ = ["create", "time"] +__all__ = ["UUID", "create", "time"] def create(when: datetime | None = None) -> UUID: