Developer Interface

ULID

class ulid.ULID(value: bytes | None = None)

The ULID object consists of a timestamp part of 48 bits and of 80 random bits.

 01AN4Z07BY      79KA1307SR9X4MV3
|----------|    |----------------|
 Timestamp          Randomness
   48bits             80bits

You usually create a new ULID-object by calling the default constructor with no arguments. In that case it will fill the timestamp part with the current datetime. To encode the object you usually convert it to a string:

>>> ulid = ULID()
>>> str(ulid)
'01E75PVKXA3GFABX1M1J9NZZNF'

classmethod from_bytes(bytes_: bytes) → U

Create a new ULID-object from sequence of 16 bytes.

classmethod from_datetime(value: datetime) → U

Create a new ULID-object from a datetime. The timestamp part of the ULID will be set to the corresponding timestamp of the datetime.

Examples

>>> from datetime import datetime
>>> ULID.from_datetime(datetime.now())
ULID(01E75QRYCAMM1MKQ9NYMYT6SAV)

classmethod from_hex(value: str) → U

Create a new ULID-object from 32 character string of hex values.

classmethod from_int(value: int) → U

Create a new ULID-object from an int.

classmethod from_str(string: str) → U

Create a new ULID-object from a 26 char long string representation.

classmethod from_timestamp(value: int | float) → U

Create a new ULID-object from a timestamp. The timestamp can be either a float representing the time in seconds (as it would be returned by time.time()) or an int in milliseconds.

Examples

>>> import time
>>> ULID.from_timestamp(time.time())
ULID(01E75QWN5HKQ0JAVX9FG1K4YP4)

classmethod from_uuid(value: UUID) → U

Create a new ULID-object from a uuid.UUID. The timestamp part will be random in that case.

Examples

>>> from uuid import uuid4
>>> ULID.from_uuid(uuid4())
ULID(27Q506DP7E9YNRXA0XVD8Z5YSG)

to_uuid() → UUID

Convert the ULID to a uuid.UUID.

to_uuid4() → UUID

Convert the ULID to a uuid.UUID compliant to version 4 of RFC 4122.

This conversion is destructive in the sense that the uuid.UUID cannot be converted back to the same ULID. This is because the bits for the variant and version information have to be set accordingly changing the original byte sequence.

Examples

>>> ulid = ULID()
>>> uuid = ulid.to_uuid4()
>>> uuid.version
4

property datetime: datetime

Return the timestamp part as timezone-aware datetime in UTC.

Examples

>>> ulid.datetime
datetime.datetime(2020, 4, 30, 14, 33, 27, 560000, tzinfo=datetime.timezone.utc)

property hex: str

Encode the ULID-object as a 32 char sequence of hex values.

property milliseconds: int

The timestamp part as epoch time in milliseconds.

Examples

>>> ulid.timestamp
1588257207560

property timestamp: float

The timestamp part as epoch time in seconds.

Examples

>>> ulid.timestamp
1588257207.56