snowflakekit 0.1.1

A fast, async Snowflake ID generator for Python.

Snowflake ID Generator

A Python library for generating unique, distributed IDs using a modified Snowflake algorithm. This library allows for easy generation of Snowflake IDs, encoding/decoding to Base62, and extracting information from the generated IDs.

Features

• Asynchronous ID generation: Supports high-throughput applications.
• Customizable bit allocation: Configurable time, node, worker, and sequence bits.
• Base62 encoding/decoding: Easily encode Snowflake IDs into a compact, URL-friendly format.
• Extractable components: Retrieve timestamp, node ID, worker ID, and sequence number from a generated Snowflake ID.

Installation

You can install the library using pip after building the package:

pip install snowflakekit

Usage

Basic Usage

Here's a quick example of how to use the Snowflake ID generator:

import asyncio
from snowflakekit import SnowflakeGenerator, SnowflakeConfig

async def main():
    generator = SnowflakeGenerator()
    snowflake_id = await generator.generate()
    print(f"Generated Snowflake ID: {snowflake_id}")

    # Base62 encoding
    encoded_id = SnowflakeGenerator.encode_base62(snowflake_id)
    print(f"Base62 Encoded ID: {encoded_id}")

    # Decoding back to Snowflake ID
    decoded_id = SnowflakeGenerator.decode_base62(encoded_id)
    print(f"Decoded Snowflake ID: {decoded_id}")

    # Extracting components from Snowflake ID
    components = generator.extract_snowflake_info(snowflake_id)
    print(f"Extracted Components: {components}")

asyncio.run(main())

Configuration

You can customize the ID generation by passing a SnowflakeConfig object to the SnowflakeGenerator. All configuration parameters are adjustable, allowing you to tailor the generator to your specific needs.

Custom Configuration Example (64-bit ID)

from snowflakekit import SnowflakeGenerator, SnowflakeConfig

config = SnowflakeConfig(
    epoch=1609459200000,  # Custom epoch (January 1, 2021)
    node_id=1,
    worker_id=2,
    time_bits=39,   # 39 bits for time
    node_bits=5,    # 5 bits for node ID (up to 32 nodes)
    worker_bits=8   # 8 bits for worker ID (up to 256 workers)
)
generator = SnowflakeGenerator(config=config)

Custom Configuration Examples for Different Bit Allocations

Example 1: 64-bit ID

• Time Bits (39 bits): Encodes the timestamp relative to the epoch, allowing up to ~17 years of milliseconds.
• Node Bits (5 bits): Allows for up to 32 unique nodes.
• Worker Bits (8 bits): Allows for up to 256 unique workers per node.
• Sequence Bits (12 bits): Automatically calculated to allow up to 4096 IDs to be generated per worker, per millisecond.

from snowflakekit import SnowflakeGenerator, SnowflakeConfig

config = SnowflakeConfig(
    epoch=1609459200000,
    node_id=1,
    worker_id=2,
    time_bits=39,
    node_bits=5,
    worker_bits=8
)
generator = SnowflakeGenerator(config=config)

Example 2: 32-bit ID

• Time Bits (21 bits): Encodes the timestamp relative to the epoch, allowing up to ~2 minutes of milliseconds.
• Node Bits (1 bit): Allows for 2 unique nodes.
• Worker Bits (6 bits): Allows for up to 64 unique workers per node.
• Sequence Bits (4 bits): Automatically calculated to allow up to 16 IDs to be generated per worker, per millisecond.

from snowflakekit import SnowflakeGenerator, SnowflakeConfig
    
config = SnowflakeConfig(
    epoch=1609459200000,
    node_id=1,
    worker_id=2,
    time_bits=21,
    node_bits=1,
    worker_bits=6,
    total_bits=32  # Adjust total bits to 32 for a 32-bit ID
)
generator = SnowflakeGenerator(config=config)

Default Bit Allocation

By default, the Snowflake ID is a 64-bit integer with the following bit allocation:

• Total Bits (64 bits): The total number of bits used to generate the ID.
• Time Bits (40 bits): Encodes the timestamp relative to the specified epoch.
• Node Bits (7 bits): Identifies the node generating the ID.
• Worker Bits (5 bits): Identifies the worker within the node.
• Sequence Bits (12 bits): A sequence counter that ensures uniqueness within the same millisecond.

Extracting Snowflake ID Components

You can extract individual components (timestamp, node ID, worker ID, and sequence) from a Snowflake ID:

from snowflakekit import SnowflakeGenerator, SnowflakeConfig
generator = SnowflakeGenerator()
snowflake_id = await generator.generate()
components = generator.extract_snowflake_info(snowflake_id)
print(components)

This will return a dictionary with the following keys:

• timestamp: The time at which the ID was generated, formatted as a human-readable string.
• node_id: The ID of the node that generated the ID.
• worker_id: The ID of the worker that generated the ID.
• sequence: The sequence number within the same millisecond.

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

Testing

To run the unit tests, use the following command:

pytest

Acknowledgements

This project is inspired by Twitter's Snowflake ID generation algorithm. Special thanks to the contributors and open-source community.