ulid/api

Defines the public API of the ulid package.

ulid.api.new() → ulid.ulid.ULID

Create a new ULID instance.

The timestamp and randomness values are created from the instance Provider.

Returns

ULID from current timestamp

Return type

ULID

ulid.api.parse(value: Union[int, float, str, bytes, bytearray, memoryview, uuid.UUID, ulid.ulid.ULID]) → ulid.ulid.ULID

Create a new ULID instance from the 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.

Parameters

value (ULIDPrimitive) – ULID value of any supported type

Returns

ULID from value

Return type

ULID

Raises

ValueError – when unable to parse a ULID from the value

ulid.api.create(timestamp: Union[int, float, str, bytes, bytearray, memoryview, datetime.datetime, ulid.ulid.Timestamp, ulid.ulid.ULID], randomness: Union[int, float, str, bytes, bytearray, memoryview, ulid.ulid.Randomness, ulid.ulid.ULID]) → ulid.ulid.ULID

Create a new ULID instance using the given timestamp and randomness values.

The following types are supported for timestamp values:

• datetime

• int

• float

• str

• memoryview

• Timestamp

• ULID

• bytes

• bytearray

The following types are supported for randomness values:

• int

• float

• str

• memoryview

• Randomness

• ULID

• bytes

• bytearray

Parameters

• timestamp (See docstring for types) – Unix timestamp in seconds

• randomness (See docstring for types) – Random bytes

Returns

ULID using given timestamp and randomness

Return type

ULID

Raises

• ValueError – when a value is an unsupported type

• ValueError – when a value is a string and cannot be Base32 decoded

• ValueError – when a value is or was converted to incorrect bit length

ulid.api.from_bytes(value: Union[bytes, bytearray, memoryview]) → ulid.ulid.ULID

Create a new ULID instance from the given bytes, bytearray, or memoryview value.

Parameters

value (bytes, bytearray, or memoryview) – 16 bytes

Returns

ULID from buffer value

Return type

ULID

Raises

ValueError – when the value is not 16 bytes

ulid.api.from_int(value: int) → ulid.ulid.ULID

Create a new ULID instance from the given int value.

Parameters

value (int) – 128 bit integer

Returns

ULID from integer value

Return type

ULID

Raises

ValueError – when the value is not a 128 bit integer

ulid.api.from_str(value: str) → ulid.ulid.ULID

Create a new ULID instance from the given str value.

Parameters

value (str) – Base32 encoded string

Returns

ULID from string value

Return type

ULID

Raises

ValueError – when the value is not 26 characters or malformed

ulid.api.from_uuid(value: uuid.UUID) → ulid.ulid.ULID

Create a new ULID instance from the given UUID value.

Parameters

value (UUID) – UUIDv4 value

Returns

ULID from UUID value

Return type

ULID

ulid.api.from_timestamp(timestamp: Union[int, float, str, bytes, bytearray, memoryview, datetime.datetime, ulid.ulid.Timestamp, ulid.ulid.ULID]) → ulid.ulid.ULID

Create a new ULID instance using a timestamp value of a supported type.

The following types are supported for timestamp values:

• datetime

• int

• float

• str

• memoryview

• Timestamp

• ULID

• bytes

• bytearray

Parameters

timestamp (See docstring for types) – Timestamp in milliseconds

Returns

ULID using given timestamp and new randomness

Return type

ULID

Raises

• ValueError – when the value is an unsupported type

• ValueError – when the value is a string and cannot be Base32 decoded

• ValueError – when the value is or was converted to something 48 bits

ulid.api.from_randomness(randomness: Union[int, float, str, bytes, bytearray, memoryview, ulid.ulid.Randomness, ulid.ulid.ULID]) → ulid.ulid.ULID

Create a new ULID instance using the given randomness value of a supported type.

The following types are supported for randomness values:

• int

• float

• str

• memoryview

• Randomness

• ULID

• bytes

• bytearray

Parameters

randomness (See docstring for types) – Random bytes

Returns

ULID using new timestamp and given randomness

Return type

ULID

Raises

• ValueError – when the value is an unsupported type

• ValueError – when the value is a string and cannot be Base32 decoded

• ValueError – when the value is or was converted to something 80 bits

class ulid.api.Timestamp(buffer: Union[bytes, bytearray, memoryview])

Represents the timestamp portion of a ULID.

• Unix time (time since epoch) in milliseconds.

• First 48 bits of ULID when in binary format.

• First 10 characters of ULID when in string format.

property str

Computes the string value of the timestamp from the underlying memoryview in Base32 encoding.

Returns

Timestamp in Base32 string form.

Return type

str

Raises

ValueError – if underlying memoryview cannot be encoded

property timestamp

Computes the Unix time (seconds since epoch) from its memoryview.

Returns

Timestamp in Unix time (seconds since epoch) form.

Return type

float

property datetime

Creates a datetime instance (assumes UTC) from the Unix time value of the timestamp with millisecond precision.

Returns

Timestamp in datetime form.

Return type

datetime

property bin

Computes the binary string value of the underlying memoryview.

Returns

Memory in binary string form

Return type

str

property bytes

Computes the bytes value of the underlying memoryview.

Returns

Memory in bytes form

Return type

bytes

property float

Computes the float value of the underlying memoryview in big-endian byte order.

Returns

Bytes in float form.

Return type

float

property hex

Computes the hexadecimal string value of the underlying memoryview.

Returns

Memory in hexadecimal string form

Return type

str

property int

Computes the integer value of the underlying memoryview in big-endian byte order.

Returns

Bytes in integer form.

Return type

int

property oct

Computes the octal string value of the underlying memoryview.

Returns

Memory in octal string form

Return type

str

class ulid.api.Randomness(buffer: Union[bytes, bytearray, memoryview])

Represents the randomness portion of a ULID.

• Cryptographically secure random values.

• Last 80 bits of ULID when in binary format.

• Last 16 characters of ULID when in string format.

property str

Computes the string value of the randomness from the underlying memoryview in Base32 encoding.

Returns

Timestamp in Base32 string form.

Return type

str

Raises

ValueError – if underlying memoryview cannot be encoded

property bin

Computes the binary string value of the underlying memoryview.

Returns

Memory in binary string form

Return type

str

property bytes

Computes the bytes value of the underlying memoryview.

Returns

Memory in bytes form

Return type

bytes

property float

Computes the float value of the underlying memoryview in big-endian byte order.

Returns

Bytes in float form.

Return type

float

property hex

Computes the hexadecimal string value of the underlying memoryview.

Returns

Memory in hexadecimal string form

Return type

str

property int

Computes the integer value of the underlying memoryview in big-endian byte order.

Returns

Bytes in integer form.

Return type

int

property oct

Computes the octal string value of the underlying memoryview.

Returns

Memory in octal string form

Return type

str

class ulid.api.ULID(buffer: Union[bytes, bytearray, memoryview])

Represents a ULID.

• 128 bits in binary format.

• 26 characters in string format.

• 16 octets.

• Network byte order, big-endian, most significant bit first.

property str

Computes the string value of the ULID from its memoryview in Base32 encoding.

Returns

ULID in Base32 string form.

Return type

str

Raises

ValueError – if underlying memoryview cannot be encoded

timestamp() → ulid.ulid.Timestamp

Creates a Timestamp instance that maps to the first 48 bits of this ULID.

Returns

Timestamp from first 48 bits.

Return type

Timestamp

randomness() → ulid.ulid.Randomness

Creates a Randomness instance that maps to the last 80 bits of this ULID.

Returns

Timestamp from first 48 bits.

Return type

Timestamp

property uuid

Creates a UUID instance of the ULID from its bytes representation.

Returns

UUIDv4 from the ULID bytes

Return type

UUID

property bin

Computes the binary string value of the underlying memoryview.

Returns

Memory in binary string form

Return type

str

property bytes

Computes the bytes value of the underlying memoryview.

Returns

Memory in bytes form

Return type

bytes

property float

Computes the float value of the underlying memoryview in big-endian byte order.

Returns

Bytes in float form.

Return type

float

property hex

Computes the hexadecimal string value of the underlying memoryview.

Returns

Memory in hexadecimal string form

Return type

str

property int

Computes the integer value of the underlying memoryview in big-endian byte order.

Returns

Bytes in integer form.

Return type

int

property oct

Computes the octal string value of the underlying memoryview.

Returns

Memory in octal string form

Return type

str