API Reference

The following section outlines the API of sonyflake.

Sonyflake

class sonyflake.Sonyflake(**options: Unpack[_SonyflakeOptions])

A distributed unique ID generator.

Parameters:

• bits_sequence (int, optional) – Number of bits allocated for the sequence number (the default is 8).

• bits_machine_id (int, optional) – Number of bits allocated for the machine ID (the default is 16).

• time_unit (datetime.timedelta, optional) – Minimum time unit used for incrementing IDs (the default is 10 milliseconds).

• start_time (datetime.datetime) – The custom epoch from which time is measured.

• machine_id (int, optional) – Custom machine ID to use (the default is the lower 16 bits of the machine’s private IP address).

• check_machine_id (Callable[[int], bool], optional) – Function to validate the generated or provided machine ID (the default is None, which disables validation).

Raises:

• ValueError – If start time is not provided.

• InvalidBitsSequence – If the provided bit length for the sequence number is invalid.

• InvalidBitsMachineID – If the provided bit length for the machine ID is invalid.

• InvalidTimeUnit – If the time unit is smaller than 1 millisecond.

• InvalidMachineID – If the provided or generated machine ID is invalid.

• StartTimeAhead – If the start time is set in the future.

next_id() → int

Return the next unique id.

Returns:

A 64-bit Sonyflake ID.

Return type:

int

Raises:

OverTimeLimit – If the elapsed time exceeds the maximum representable value.

await next_id_async() → int

Return the next unique id.

This coroutine is the asynchronous version of Sonyflake.next_id() and is intended for use in asynchronous applications.

Added in version 2.0.

Returns:

A 64-bit Sonyflake ID.

Return type:

int

Raises:

OverTimeLimit – If the elapsed time exceeds the maximum representable value.

to_time(sonyflake_id: int) → datetime

Convert a Sonyflake ID to its corresponding UTC datetime.

Parameters:

sonyflake_id (int) – The Sonyflake ID to convert.

Returns:

The UTC datetime corresponding to the given ID.

Return type:

datetime.datetime

compose(dt: datetime, sequence: int, machine_id: int) → int

Compose a Sonyflake ID from datetime, sequence, and machine ID.

Changed in version 2.0: The dt parameter no longer needs to be in UTC and maybe timezone-aware or naieve. If dt is naive (has no timezone), it is assumed to be in the system local timezone.

Parameters:

• dt (datetime.datetime) – The datetime at which the ID is generated.

• sequence (int) – A number between 0 and 2^bits_sequence - 1 (inclusive).

• machine_id (int) – A number between 0 and 2^bits_machine_id - 1 (inclusive).

Returns:

The composed Sonyflake ID.

Return type:

int

Raises:

• StartTimeAhead – If the datetime is before the configured start time.

• OverTimeLimit – If the elapsed time exceeds the representable range.

• InvalidSequence – If the sequence value is out of range.

• InvalidMachineID – If the machine ID is out of range.

decompose(sonyflake_id: int) → DecomposedSonyflake

Decompose a Sonyflake ID into its components.

Parameters:

sonyflake_id (int) – The Sonyflake ID to decompose.

Returns:

A named tuple with the fields: time, sequence, machine_id.

Return type:

DecomposedSonyflake

DecomposedSonyflake

class sonyflake.DecomposedSonyflake(time: int, sequence: int, machine_id: int)

Represents a decomposed Sonyflake.

This structure holds the individual components of a 64-bit Sonyflake ID.

Changed in version 2.0: The id attribute was removed.

time

The time portion of the ID.

Type:

int

sequence

The sequence number portion of the ID.

Type:

int

machine_id

The machine identifier portion of the ID.

Type:

int