Core API

Core API Reference

TimeSeed provides a set of top-level convenience functions that use a default globally shared generator. These functions allow you to get started quickly without manually configuring a generator instance.

TimeSeed provides a set of top-level convenience functions that use a default globally shared generator. These functions allow you to get started quickly without manually configuring a generator instance.

Convenience Generation Functions

timeseed.generate() -> int

Generates a 128-bit unique identifier using the default configuration.

  • Returns: int (128-bit integer)
  • Example:
    import timeseed
id_val = timeseed.generate()
# Example output: 99478426022790869e7a515

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

Generates a TimeSeed ID formatted as a 32-character hexadecimal string.

  • Parameters:
    • uppercase (bool, optional): Forces uppercase format when True, lowercase when False. Uses the config default if not provided.
  • Returns: str
  • Example:
    hex_id = timeseed.generate_hex()
# Example output: "0a1b2c3d4e5f6789012345678abcdef0"

timeseed.generate_base62() -> str

Generates a TimeSeed ID formatted as a URL-safe, 22-character base62 string.

  • Returns: str
  • Example:
    b62_id = timeseed.generate_base62()
# Example output: "2jk3Nm5pQ8rS1tU7vW9xYz"

timeseed.generate_base32() -> str

Generates a TimeSeed ID formatted as a Crockford base32, 26-character string.

  • Returns: str
  • Example:
    b32_id = timeseed.generate_base32()
# Example output: "A1B2C3D4E5F6G7H8J9K0M1N2P3"

timeseed.generate_binary() -> str

Generates a TimeSeed ID formatted as a 128-character binary string of 0s and 1s.

  • Returns: str
  • Example:
    bin_id = timeseed.generate_binary()
# Example output: "101010001011001100110100..."

timeseed.generate_batch(count: int, format_type: str = "integer") -> List[Union[int, str]]

Generates multiple TimeSeed IDs efficiently in a single batch operation.

  • Parameters:
    • count (int): Number of IDs to generate.
    • format_type (str): The string representing target output format ("integer", "hex", "base62", "base32", "binary"). Default is "integer".
  • Returns: List[Union[int, str]]
  • Example:
    ids = timeseed.generate_batch(100, format_type="hex")

Convenience Decoding Functions

timeseed.decode(id_value: int) -> TimeSeedComponents

Decodes an integer TimeSeed ID into its constituent parts.

  • Parameters:
    • id_value (int): The 128-bit integer ID.
  • Returns: TimeSeedComponents (object containing decoded fields)
  • Example:
    components = timeseed.decode(id_val)
print(components.generated_at) # Datetime object
print(components.machine_id)   # int

timeseed.decode_hex(hex_str: str) -> TimeSeedComponents

Decodes a hexadecimal TimeSeed ID string.

  • Parameters:
    • hex_str (str): 32-character hex representation.
  • Returns: TimeSeedComponents

timeseed.decode_base62(base62_str: str) -> TimeSeedComponents

Decodes a base62 TimeSeed ID string.

  • Parameters:
    • base62_str (str): 22-character base62 representation.
  • Returns: TimeSeedComponents

timeseed.decode_base32(base32_str: str) -> TimeSeedComponents

Decodes a base32 TimeSeed ID string.

  • Parameters:
    • base32_str (str): 26-character base32 representation.
  • Returns: TimeSeedComponents

Global Generator Configuration

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

Overrides configuration properties of the default global generator instance.

  • Example:
    import timeseed
# Optimize default generator for high throughput
config = timeseed.PresetConfigs.high_throughput()
timeseed.configure_default(config, machine_id=12, datacenter_id=3)

timeseed.reset_default() -> None

Resets the default generator, clearing customized configurations and recreating it with default values on next use.

Built withSourcey