diff --git a/README.md b/README.md index 888cd35..cb1a027 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ # 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 UUIDv7s with creation times, and for extracting the time from a UUID. -ℹ️ 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). +ℹ️ At the time of writing, Python had no UUIDv7 support. It does now, but still doesn't allow providing or extracting timestamps, which we do. Beware that there is also an abandoned package named `uuid7` that uses a draft RFC and produces all wrong timestamps. -- **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. +- **Standards-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 (milli)seconds, custom UUID types, or bare strings, as used by alternatives such as `uuid7-rs`. +- **Lightweight**: A tiny pure-Python module with no dependencies, fast enough to process about a million UUIDv7s per second per CPU core. ## Installation @@ -13,7 +14,7 @@ A simple module for generating UUIDv7 that contain creation timestamps. Another pip install uuid7-standard ``` -Or for your project using [uv](https://docs.astral.sh/uv/): +Or, add to your project using [uv](https://docs.astral.sh/uv/): ```sh uv add uuid7-standard @@ -23,20 +24,18 @@ uv add uuid7-standard ```python import uuid7 +from datetime import datetime, UTC +from uuid import UUID -# Create a random UUIDv7 with current timestamp, same as uuid.uuid7() +# Create a random UUIDv7 with the current timestamp, same as uuid.uuid7() u = uuid7.create() print(str(u), u.bytes) -# Create with specific timestamp -from datetime import datetime, UTC - +# Create one with a specific timestamp when = datetime(1970, 1, 1, tzinfo=UTC) u = uuid7.create(when) -# Extract timestamp -from uuid import UUID - +# Extract the timestamp u = UUID('00000000-0000-7dac-b3e3-ecb571bb3e2f') timestamp = uuid7.time(u) # 1970-01-01 UTC ``` @@ -45,12 +44,14 @@ timestamp = uuid7.time(u) # 1970-01-01 UTC 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. +The current time is used unless `when` is passed as a `datetime` (local time or timezone-aware). This is useful for creating multiple UUIDv7s with precisely the same timestamp. ### `uuid7.time(u: UUID|str) -> datetime` -Extract the timestamp from a UUIDv7. Raises ValueError if the UUID is not a UUIDv7. +Extract the timestamp from a UUIDv7. Raises `ValueError` if the UUID is not a UUIDv7. -### `uuid7.UUID` re-export of stdlib UUID +### `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. +Useful when you want to indicate explicitly that a value is expected to be UUIDv7 while avoiding a separate `import uuid`. + +Note that `uuid7.UUID is uuid.UUID` and does not enforce the UUIDv7 format. It does, however, help humans and coding agents avoid accidentally using `uuid4()` when working with such values. diff --git a/pyproject.toml b/pyproject.toml index 04dac40..6b41c61 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,21 +1,16 @@ [project] name = "uuid7-standard" -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." +version = "1.1.2" +import-names = ["uuid7"] +description = "Pure Python UUIDv7 with datetime-based creation and timestamp extraction, filling gaps in stdlib and other implementations." readme = "README.md" -requires-python = ">=3.8" -dependencies = [] -authors = [ - {name = "Leo Vasanko"}, -] -keywords = ["uuid", "uuid7", "timestamp", "ordering", "database", "primary-key"] +requires-python = ">=3.10" +authors = [{name = "Leo Vasanko"}] +keywords = ["UUIDv7", "rfc9562", "uuid", "datetime"] +license = "MIT OR Unlicense" classifiers = [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", - "License :: OSI Approved :: MIT License", - "License :: Public Domain", - "Programming Language :: Python :: 3", - "Topic :: Software Development :: Libraries :: Python Modules", "Topic :: Utilities", ] @@ -28,4 +23,4 @@ requires = ["hatchling"] build-backend = "hatchling.build" [tool.hatch.build.targets.wheel] -packages = ["uuid7.py"] +only-include = ["uuid7.py"]