Metadata-Version: 2.5
Name: uuid7-standard
Version: 1.1.1
Summary: UUIDv7 with the final standard. Not to be confused with the uuid7 package on pypi, based on a draft version that was very different.
Project-URL: Repository, https://git.zi.fi/LeoVasanko/uuid7-standard
Project-URL: Issues, https://github.com/LeoVasanko/uuid7-standard
Author: Leo Vasanko
Keywords: database,ordering,primary-key,timestamp,uuid,uuid7
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: Public Domain
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# UUIDv7 for Python

A simple module for generating UUIDv7 that contain creation timestamps. Another function for extracting the time of an 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).

- **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.

## Installation

```sh
pip install uuid7-standard
```

Or for your project using [uv](https://docs.astral.sh/uv/):

```sh
uv add uuid7-standard
```

## Usage

```python
import uuid7

# Create a random UUIDv7 with current timestamp, same as uuid.uuid7()
u = uuid7.create()
print(str(u), u.bytes)

# Create with specific timestamp
from datetime import datetime, UTC

when = datetime(1970, 1, 1, tzinfo=UTC)
u = uuid7.create(when)

# Extract timestamp
from uuid import UUID

u = UUID('00000000-0000-7dac-b3e3-ecb571bb3e2f')
timestamp = uuid7.time(u)  # 1970-01-01 UTC
```

### `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.

### `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.
