Sqids Python

Common errors

• TypeError: 'list' object cannot be interpreted as an integer

  cause The `encode` method expects a sequence of non-negative integers (e.g., `[1, 2, 3]`), but a single integer was passed without being wrapped in a list or tuple. This error is not specific to Sqids but a common Python mistake.
  fix Ensure that the numbers passed to `sqids.encode()` are always within a list or tuple, even if it's a single number. For example, `sqids.encode([123])` instead of `sqids.encode(123)`.

• ValueError: alphabet cannot contain multibyte characters

  cause Attempting to initialize `Sqids` with a custom alphabet containing characters that are not single-byte (e.g., emojis or certain Unicode characters). This restriction was introduced in v0.3.0.
  fix When defining a custom `alphabet`, ensure all characters are single-byte ASCII compatible. Remove any emojis or multi-byte Unicode characters from the alphabet string.

Warnings

• gotcha Due to the algorithm's design, multiple distinct IDs might decode back into the same sequence of numbers. If canonical IDs are critical for your application, you must manually re-encode decoded numbers and verify that the newly generated ID matches the original.
  Fix: After decoding an ID, re-encode the resulting numbers and compare the new ID with the original to ensure canonical representation if required by your application logic.
• breaking Version 0.3.0 introduced significant breaking changes, primarily an algorithm fine-tuning that causes IDs generated from the same inputs to change. Additionally, the `min_length` upper limit increased to 255, `min_value()` and `max_value()` functions were removed, and the minimum alphabet length changed from 5 to 3. The alphabet can no longer contain multibyte characters.
  Fix: If upgrading from versions prior to 0.3.0, be aware that existing Sqids will no longer decode to their original numbers using the new algorithm, or vice-versa. Update any stored IDs or decoding logic accordingly. Review the changelog for specific parameter and function changes.
• gotcha Sqids is not an encryption library and should not be used for sensitive data. Generated IDs can be easily decoded back into their original numbers, which could inadvertently reveal information such as user counts if used for user IDs.
  Fix: Avoid using Sqids for any data that requires cryptographic security or where the underlying numerical values must remain confidential. Use dedicated encryption libraries for sensitive data.
• gotcha For optimal performance, especially with blocklist checks, it is highly recommended to instantiate the `Sqids` class once and reuse that instance throughout your application. Version 0.5.0 improved encoding speed by ~85% but requires more calculation during instantiation.
  Fix: Instantiate `Sqids()` at the application's startup or as a singleton, and pass the same instance to all parts of your code that need to encode or decode IDs.

Install

• pip install sqids Install with pip

Imports

• Sqids

  from sqids import Sqids

Quickstart

Initializes the Sqids encoder/decoder and demonstrates basic encoding and decoding of numbers, as well as enforcing a minimum ID length.

from sqids import Sqids

sqids = Sqids()

# Encode numbers into a Sqid
numbers_to_encode = [1, 2, 3]
id = sqids.encode(numbers_to_encode)
print(f"Encoded ID: {id}") # Example: 86Rf07

# Decode a Sqid back into numbers
decoded_numbers = sqids.decode(id)
print(f"Decoded numbers: {decoded_numbers}") # Example: [1, 2, 3]

# Enforce a minimum length for the ID
sqids_min_length = Sqids(min_length=10)
id_padded = sqids_min_length.encode([1, 2, 3])
print(f"Padded ID: {id_padded}") # Example: 86Rf07xd4z