Metadata-Version: 2.4
Name: uuid7-standard
Version: 1.0.0
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: Homepage, https://git.zi.fi/leo/uuid7-python
Project-URL: Repository, https://github.com/LeoVasanko/uuid7-python
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.10
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.

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.

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

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

Extract the timestamp from a UUIDv7. Raises ValueError if the UUID is not a UUIDv7.
