TimeSeed Generator

The TimeSeed class is the core component of the TimeSeed library, responsible for generating, decoding, and converting unique, chronologically ordered 128-bit identifiers.

Class Definition

timeseed.TimeSeed(config: Optional[TimeSeedConfig] = None, machine_id: Optional[int] = None, datacenter_id: Optional[int] = None)

Initializes a new TimeSeed generator instance.

• Parameters:
  • config (TimeSeedConfig, optional): Custom configuration parameters. Uses default configuration if not provided.
  • machine_id (int, optional): Manually overrides the machine identifier from the config or environment.
  • datacenter_id (int, optional): Manually overrides the datacenter identifier from the config or environment.
• Raises:
  • MachineIdError: If the resolved machine ID exceeds maximum allowed limit.
  • DatacenterIdError: If the resolved datacenter ID exceeds maximum allowed limit.

---

Generation Methods

generate() -> int

Generates a new 128-bit unique identifier based on current system time, configured machine ID, datacenter ID, and sequence counter.

• Returns: int (128-bit integer)
• Raises:
  • ClockBackwardError: If the system clock moves backward significantly.
  • SequenceOverflowError: If sequence limit is reached in a single millisecond and sequence_overflow_wait config is set to False.

generate_hex(uppercase: Optional[bool] = None) -> str

Generates a new ID as a 32-character hexadecimal string.

• Parameters:
  • uppercase (bool, optional): Overrides default uppercase/lowercase config.
• Returns: str

generate_base62() -> str

Generates a new ID as a 22-character URL-safe base62 string.

• Returns: str

generate_base32() -> str

Generates a new ID as a 26-character Crockford base32 string.

• Returns: str

generate_binary() -> str

Generates a new ID as a 128-character binary representation string.

• Returns: str

---

Conversion & Serialization Methods

to_hex(id_value: int, uppercase: Optional[bool] = None) -> str

Converts an existing integer TimeSeed ID to a 32-character hexadecimal string.

to_base62(id_value: int) -> str

Converts an existing integer TimeSeed ID to a 22-character URL-safe base62 string.

to_base32(id_value: int) -> str

Converts an existing integer TimeSeed ID to a 26-character Crockford base32 string.

to_binary(id_value: int) -> str

Converts an existing integer TimeSeed ID to a 128-character binary string.

convert_format(id_value: int, target_format: Union[IDFormat, str]) -> str

Converts an existing integer TimeSeed ID to the specified format. The target_format can be an IDFormat enum value or a string matching "hex", "base62", "base32", "binary", or "integer".

---

Instance Decoding & Validation Methods

decode(id_value: int) -> TimeSeedComponents

Decodes an integer TimeSeed ID into its constituent components relative to the current generator's bit configuration.

decode_hex(hex_str: str) -> TimeSeedComponents

Decodes a hexadecimal string representation of a TimeSeed ID.

decode_base62(base62_str: str) -> TimeSeedComponents

Decodes a base62 string representation of a TimeSeed ID.

decode_base32(base32_str: str) -> TimeSeedComponents

Decodes a base32 string representation of a TimeSeed ID.

validate_id(id_value: int) -> bool

Validates whether the structure of an ID is compatible with the generator's current configuration.