Developer Interface

ULID

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

classmethod from_bytes(bytes_: bytes) → Self

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

classmethod from_datetime(value: datetime) → Self

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) → Self

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

classmethod from_int(value: int) → Self

Create a new ULID-object from an int.

classmethod from_str(string: str) → Self

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

classmethod from_timestamp(value: float) → Self

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) → Self

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)

classmethod parse(value: Any) → Self

Create a new ULID-object from a given value.

Note

This method should only be used when the caller is trying to parse a ULID from a value when they’re unsure what format/primitive type it will be given in.

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.milliseconds
1588257207560

provider = <ulid.ValueProvider object>

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'

Parameters:

value (bytes, None) – A sequence of 16 bytes representing an encoded ULID.

Raises:

ValueError – If the provided value is not a valid encoded ULID.

property timestamp: float

The timestamp part as epoch time in seconds.

Examples

>>> ulid.timestamp
1588257207.56