Sqids Python

https://github.com/sqids/sqids-python
Admin
Sqids Python is a library for generating unique, URL-safe, and randomized short IDs from multiple...
Tokens:10,247
Snippets:79
Trust Score:7.7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Constructor example — defaults

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Creates a Sqids instance with default settings and encodes a list of integers. The output is an example ID like "86Rf07".

```python
from sqids import Sqids

sqids = Sqids()  # default alphabet, min_length=0, default blocklist
id_ = sqids.encode([1, 2, 3])
print(id_)  # e.g. "86Rf07"
```

--------------------------------

### Install sqids with pip

Source: https://github.com/sqids/sqids-python/blob/main/README.md

Install the sqids package from PyPI using pip.

```bash
pip install sqids
```

--------------------------------

### Basic decode example

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Basic decode example. Decodes a known ID and verifies round-trip encoding/decoding with an assertion.

```python
from sqids import Sqids

sqids = Sqids()
numbers = sqids.decode("86Rf07")
print(numbers)  # [1, 2, 3]

assert sqids.decode(sqids.encode([42, 7])) == [42, 7]
```

--------------------------------

### Create Sqids instance with defaults

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/configuration.md

Use this snippet to create a Sqids instance with all default configuration options. This is the simplest way to start using the library when no customization is needed.

```python
from sqids import Sqids

sqids = Sqids()
```

--------------------------------

### Constructor example — validation error handling

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Shows how validation errors are raised for invalid alphabet, min_length, and type. Catches ValueError and TypeError and prints the error messages.

```python
from sqids import Sqids

try:
    Sqids(alphabet="aabc")          # duplicate 'a'
except ValueError as exc:
    print(f"invalid alphabet: {exc}")

try:
    Sqids(min_length=300)           # > 255
except ValueError as exc:
    print(f"invalid min_length: {exc}")

try:
    Sqids(min_length=True)          # bool is rejected even though bool subclasses int
except TypeError as exc:
    print(f"invalid type: {exc}")
```

--------------------------------

### DEFAULT_BLOCKLIST example entries

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/constants.md

Example entries from the DEFAULT_BLOCKLIST list literal, which contains 560 profanity words with leetspeak variants.

```python
[
    "0rgasm",
    "1d10t",
    "a11upat0",
    "anus",
    "b1tch",
    "bastardo",
    "boob",
    "c0ck",
    "coglione",
    "f1ca",
    "fuck",
    "n1gger",
    "orgasm",
    "puta",
    "retard",
    "shit",
    ...
]
```

--------------------------------

### Sqids.__init__

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/configuration.md

Documentation for the Sqids constructor, including all options, defaults, validation rules, and fast-path default detection.

```APIDOC
## [CONSTRUCTOR] Sqids.__init__

### Description
Initializes a new Sqids instance with configurable alphabet, minimum length, and blocklist. All configuration is passed through this single constructor; there are no configuration files or environment variables.

### Method
Constructor

### Endpoint
Sqids.__init__

### Parameters
#### Constructor Parameters
- **alphabet** (str) - Optional - Characters that may appear in generated IDs. Must be at least 3 characters, all unique, all ASCII (no multibyte characters). Default: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
- **min_length** (int) - Optional - Minimum length every encoded ID is padded to. Must be an int (not a bool) between 0 and 255 inclusive. Default: 0
- **blocklist** (List[str]) - Optional - Words that must not appear in generated IDs. Pre-filtered at construction; entries shorter than 3 characters or containing characters outside the lowercased alphabet are ignored. Passing an empty list/set disables blocklisting. Default: DEFAULT_BLOCKLIST (560 profanity words incl. leetspeak variants)

### Request Example
```python
sqids = Sqids(
    alphabet="abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
    min_length=0,
    blocklist=["word1", "word2"]
)
```

### Response
#### Success Response
Returns a new Sqids instance configured with the provided options.

#### Error Handling
- **ValueError** - Raised if alphabet contains multibyte characters, alphabet length is less than 3, alphabet contains duplicate characters, or min_length is less than 0 or greater than 255.
- **TypeError** - Raised if min_length is not an int (including bool).
```

--------------------------------

### Package entry point __init__.py

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

The contents of the package entry point file `sqids/__init__.py`, which re-exports the Sqids class and defines `__all__`. This is the file that makes the direct import work.

```python
from .sqids import Sqids

__all__ = ["Sqids"]
```

--------------------------------

### Import Sqids from package entry point

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Shows two supported ways to import the Sqids class: directly from the package entry point (recommended) or via the module attribute. Use this when you need to access the Sqids class in your code.

```python
from sqids import Sqids        # supported (entry point, `__all__ = ["Sqids"]`)
import sqids
sqids.Sqids()                  # also supported (module attribute)
```

--------------------------------

### Import and instantiate Sqids

Source: https://github.com/sqids/sqids-python/blob/main/README.md

Import the Sqids class and create an instance for encoding and decoding.

```python
from sqids import Sqids
sqids = Sqids()
```

--------------------------------

### Sqids.__init__

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Initializes a new Sqids instance with configurable alphabet, minimum length, and blocklist. Validates inputs and pre-processes the blocklist for efficient filtering.

```APIDOC
## Sqids.__init__

### Description
Initializes a new Sqids instance with configurable alphabet, minimum length, and blocklist. Validates inputs and pre-processes the blocklist for efficient filtering.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    alphabet: str = DEFAULT_ALPHABET,
    min_length: int = DEFAULT_MIN_LENGTH,
    blocklist: List[str] = DEFAULT_BLOCKLIST,
):
```

### Parameters
- **alphabet** (str) - Optional - Character set used to build IDs. Must be at least 3 unique ASCII characters; must not contain multibyte characters. It is shuffled once at construction as part of the ID-generation algorithm. Default: `DEFAULT_ALPHABET`.
- **min_length** (int) - Optional - Minimum length that every encoded ID is padded to. Must be an `int` between 0 and 255 (inclusive). Default: `DEFAULT_MIN_LENGTH` (`0`).
- **blocklist** (List[str]) - Optional - Words that must never appear in generated IDs. Pre-filtered into three sets at construction; entries shorter than 3 characters or containing characters outside the (lowercased) alphabet are silently ignored. Default: `DEFAULT_BLOCKLIST`.

### Validation Errors
- **ValueError** "Alphabet cannot contain multibyte characters" - Raised when any `ord(char) > 127` in `alphabet`.
- **ValueError** "Alphabet length must be at least 3" - Raised when `len(alphabet) < 3`.
- **ValueError** "Alphabet must contain unique characters" - Raised when duplicate characters exist in `alphabet`.
- **TypeError** "Minimum length must be an int" - Raised when `min_length` is not an `int`, or is a `bool`.
- **ValueError** "Minimum length has to be between 0 and 255" - Raised when `min_length < 0` or `min_length > 255`.

### Blocklist Pre-processing Behavior
When `blocklist is DEFAULT_BLOCKLIST` and `alphabet is DEFAULT_ALPHABET`, the constructor assigns pre-filtered module constants directly. Otherwise, it filters supplied words:
- A word is skipped if `len(word) < 3`.
- A word is skipped if its (lowercased) character set is not a subset of the lowercased alphabet.
- A 3-character word goes to the `exact_match` set (blocked only when the whole ID is that word).
- A longer word containing digits goes to `match_at_ends` (blocked when it appears at the start or end of the ID).
- Any other word goes to `match_anywhere` (blocked when it appears anywhere in the ID).
All comparisons are case-insensitive.

### Example - Defaults
```python
from sqids import Sqids

sqids = Sqids()  # default alphabet, min_length=0, default blocklist
id_ = sqids.encode([1, 2, 3])
print(id_)  # e.g. "86Rf07"
```

### Example - Validation Error Handling
```python
from sqids import Sqids

try:
    Sqids(alphabet="aabc")          # duplicate 'a'
except ValueError as exc:
    print(f"invalid alphabet: {exc}")

try:
    Sqids(min_length=300)           # > 255
except ValueError as exc:
    print(f"invalid min_length: {exc}")

try:
    Sqids(min_length=True)          # bool is rejected even though bool subclasses int
except TypeError as exc:
    print(f"invalid type: {exc}")
```
```

--------------------------------

### Import public constants from sqids.constants

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/constants.md

Import the public constants from the sqids.constants module.

```python
from sqids.constants import DEFAULT_ALPHABET, DEFAULT_MIN_LENGTH, DEFAULT_BLOCKLIST
```

--------------------------------

### Customize blocklist

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/configuration.md

Customize the blocklist behavior. Passing a list blocks the word "86Rf07", resulting in "se8ojk" for [1, 2, 3]; an empty list disables blocklisting, and any collection of strings is accepted at runtime.

```python
from sqids import Sqids

# Block a specific word wherever it appears
sqids = Sqids(blocklist=["86Rf07"])
id_ = sqids.encode([1, 2, 3])   # "se8ojk" (skips the blocked ID)

# Disable blocklisting entirely
sqids = Sqids(blocklist=[])

# Any sequence/collection of strings is accepted at runtime (annotation is List[str])
sqids = Sqids(blocklist={"word1", "word2"})
```

--------------------------------

### _exact_match private constant definition

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/constants.md

Private set of 7 three-letter words blocked only when the whole ID equals the word.

```python
_exact_match = {
    "ass",
    "cum",
    "fag",
    "g00",
    "g0o",
    "go0",
    "goo",
}
```

--------------------------------

### Set minimum ID length with min_length=10

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/configuration.md

Configure Sqids to generate IDs with a minimum length of 10 characters. The encoded ID for [1, 2, 3] is "86Rf07xd4z", and the assertion verifies the length.

```python
from sqids import Sqids

# All IDs are at least 10 characters long
sqids = Sqids(min_length=10)
id_ = sqids.encode([1, 2, 3])   # "86Rf07xd4z"
assert len(id_) == 10
```

--------------------------------

### Sqids.decode

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Documentation for the Sqids.decode method, which decodes an ID string back into the original sequence of non-negative integers.

```APIDOC
## Sqids.decode

### Description
Decodes an ID string back into the original sequence of non-negative integers. Returns an empty list for invalid input rather than raising an exception.

### Method
`decode(self, id_: str) -> List[int]`

### Parameters
- `id_` (str) - Required - The ID string to decode. May be empty; any character not present in the instance's shuffled alphabet makes the whole input invalid.

### Return Type
`List[int]` - The decoded number sequence. An empty list is returned for the empty string or for any invalid input; a malformed ID is **not** an exception.

### Behavior Notes
- `decode("")` returns `[]`.
- If any character of `id_` is not in the shuffled alphabet, returns `[]`.
- Returns `[]` if a separator character is found at the start of an ID chunk (handles the "repeating reserved character" edge case).

### Example — basic decode

```python
from sqids import Sqids

sqids = Sqids()
numbers = sqids.decode("86Rf07")
print(numbers)  # [1, 2, 3]

assert sqids.decode(sqids.encode([42, 7])) == [42, 7]
```

### Example — invalid input handling

```python
from sqids import Sqids

sqids = Sqids()

print(sqids.decode(""))      # []  — empty string
print(sqids.decode("*"))     # []  — '*' is not in the alphabet

# canonical-ID check: verify a decoded value really belongs to its ID
id_ = sqids.encode([1, 2, 3])
numbers = sqids.decode(id_)
if sqids.encode(numbers) != id_:
    print("non-canonical ID; re-encode and compare before trusting it")
```
```

--------------------------------

### Sqids class

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Reference for the Sqids class, including its constructor and encode/decode methods.

```APIDOC
## Class: Sqids

### Description
Factory-style configuration object that generates reversible, URL-safe, unique IDs from one or more non-negative integers. State configured at construction time (shuffled alphabet, minimum length, pre-filtered blocklist) is captured per instance; the instance is then used for `encode()` / `decode()` calls.

### Constructor
`Sqids()`

### Methods
- `encode()` - Encodes one or more non-negative integers into a Sqid.
- `decode()` - Decodes a Sqid back into the original numbers.

### Usage
```python
from sqids import Sqids

sqids = Sqids()
id = sqids.encode(1, 2, 3)  # "86Rf07"
numbers = sqids.decode(id)  # [1, 2, 3]
```
```

--------------------------------

### Set minimum ID length with min_length

Source: https://github.com/sqids/sqids-python/blob/main/README.md

Enforce a minimum length for generated IDs by passing min_length to the constructor.

```python
sqids = Sqids(min_length=10)
id = sqids.encode([1, 2, 3]) # "86Rf07xd4z"
numbers = sqids.decode(id) # [1, 2, 3]
```

--------------------------------

### Sqids constructor signature

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

The full signature of the Sqids constructor, copied from sqids/sqids.py:16. Shows the default values for alphabet, min_length, and blocklist.

```python
def __init__(
    self,
    alphabet: str = DEFAULT_ALPHABET,
    min_length: int = DEFAULT_MIN_LENGTH,
    blocklist: List[str] = DEFAULT_BLOCKLIST,
):
```

--------------------------------

### Sqids.encode

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Documentation for the Sqids.encode method, which encodes a sequence of non-negative integers into a URL-safe ID string.

```APIDOC
## Sqids.encode

### Description
Encodes a sequence of non-negative integers into a URL-safe ID string. The generated ID contains only characters from the shuffled alphabet and never contains blocked words.

### Method
`encode(self, numbers: Sequence[int]) -> str`

### Parameters
- `numbers` (Sequence[int]) - Required - One or more non-negative integers to encode (list, tuple, or any Sequence). Each number must be between 0 and sys.maxsize inclusive.

### Return Type
`str` - The generated ID. Contains only characters from the shuffled alphabet; it is URL-safe because it never contains blocked words.

### Throws
- `ValueError` "Encoding supports numbers between 0 and {sys.maxsize}" - Raised when any number in `numbers` is < 0 or > sys.maxsize.

### Behavior Notes
- `encode([])` (empty sequence) returns `""`.
- If the first generated ID is blocked, encoding is retried with an incremented offset via the private `__encode_numbers`; if `increment` exceeds the alphabet length, `__encode_numbers` raises `ValueError("Reached max attempts to re-generate the ID")` — reachable only when the blocklist blocks effectively every possible ID (e.g. `alphabet="abc"`, `min_length=3`, `blocklist={"cab", "abc", "bca"}`).
- IDs are padded to `min_length` when shorter.
- IDs are non-canonical by design: **multiple IDs can decode back into the same number sequence**. If canonical IDs are required, re-encode the decoded numbers and compare with the original ID.

### Example — basic encode/decode round trip

```python
from sqids import Sqids

sqids = Sqids()
id_ = sqids.encode([1, 2, 3])     # "86Rf07"
print(id_)
print(sqids.decode(id_))          # [1, 2, 3]

# multiple numbers, including the maximum value
import sys
print(sqids.encode([0, 0, 0, 1, 2, 3, 100, sys.maxsize]))
```

### Example — error handling

```python
from sqids import Sqids

sqids = Sqids()

try:
    sqids.encode([-1])               # negative numbers are rejected
except ValueError as exc:
    print(exc)  # "Encoding supports numbers between 0 and 9223372036854775807"

try:
    sqids.encode([sys.maxsize + 1])
except ValueError as exc:
    print(exc)
```
```

--------------------------------

### Basic encode/decode round trip

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Basic encode/decode round trip. Shows encoding a list of numbers, decoding the resulting ID, and encoding multiple numbers including sys.maxsize.

```python
from sqids import Sqids

sqids = Sqids()
id_ = sqids.encode([1, 2, 3])     # "86Rf07"
print(id_)
print(sqids.decode(id_))          # [1, 2, 3]

# multiple numbers, including the maximum value
import sys
print(sqids.encode([0, 0, 0, 1, 2, 3, 100, sys.maxsize]))
```

--------------------------------

### Decode invalid input handling

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Invalid input handling for decode. Shows that empty strings and characters not in the alphabet return an empty list, and demonstrates a canonical-ID check.

```python
from sqids import Sqids

sqids = Sqids()

print(sqids.decode(""))      # []  — empty string
print(sqids.decode("*"))     # []  — '*' is not in the alphabet

# canonical-ID check: verify a decoded value really belongs to its ID
id_ = sqids.encode([1, 2, 3])
numbers = sqids.decode(id_)
if sqids.encode(numbers) != id_:
    print("non-canonical ID; re-encode and compare before trusting it")
```

--------------------------------

### Blocklist words from IDs

Source: https://github.com/sqids/sqids-python/blob/main/README.md

Prevent specific words from appearing in generated IDs by passing a blocklist to the constructor.

```python
sqids = Sqids(blocklist=["86Rf07"])
id = sqids.encode([1, 2, 3]) # "se8ojk"
numbers = sqids.decode(id) # [1, 2, 3]
```

--------------------------------

### DEFAULT_MIN_LENGTH constant definition

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/constants.md

Default minimum length integer used as the default for the min_length parameter of Sqids.__init__.

```python
DEFAULT_MIN_LENGTH = 0
```

--------------------------------

### Encode and decode numbers with Sqids

Source: https://github.com/sqids/sqids-python/blob/main/README.md

Encode a list of numbers into a short ID and decode it back. Note that multiple IDs can decode to the same sequence; re-encode to check canonicality if needed.

```python
sqids = Sqids()
id = sqids.encode([1, 2, 3]) # "86Rf07"
numbers = sqids.decode(id) # [1, 2, 3]
```

--------------------------------

### Custom alphabet for randomized IDs

Source: https://github.com/sqids/sqids-python/blob/main/README.md

Randomize IDs by providing a custom alphabet to the Sqids constructor.

```python
sqids = Sqids(alphabet="FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE")
id = sqids.encode([1, 2, 3]) # "B4aajs"
numbers = sqids.decode(id) # [1, 2, 3]
```

--------------------------------

### DEFAULT_ALPHABET constant definition

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/constants.md

Default alphabet string of 62 characters used as the default for the alphabet parameter of Sqids.__init__.

```python
DEFAULT_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
```

--------------------------------

### Encode error handling

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Error handling for encode. Shows that negative numbers and numbers greater than sys.maxsize raise ValueError with the message 'Encoding supports numbers between 0 and {sys.maxsize}'.

```python
from sqids import Sqids

sqids = Sqids()

try:
    sqids.encode([-1])               # negative numbers are rejected
except ValueError as exc:
    print(exc)  # "Encoding supports numbers between 0 and 9223372036854775807"

try:
    sqids.encode([sys.maxsize + 1])
except ValueError as exc:
    print(exc)
```

--------------------------------

### Sqids.decode signature

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Full signature of the Sqids.decode method, copied exactly from sqids/sqids.py:123. It takes an ID string and returns a list of integers.

```python
def decode(self, id_: str) -> List[int]:
```

--------------------------------

### Sqids.encode signature

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

Full signature of the Sqids.encode method, copied exactly from sqids/sqids.py:73. It takes a sequence of non-negative integers and returns a string ID.

```python
def encode(self, numbers: Sequence[int]) -> str:
```

--------------------------------

### Class definition of Sqids

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/api-reference/sqids.md

The class definition of Sqids. The class is a factory-style configuration object that captures state at construction time (shuffled alphabet, minimum length, pre-filtered blocklist) and is then used for encode() and decode() calls.

```python
class Sqids:
```

--------------------------------

### Encode with custom alphabet

Source: https://github.com/sqids/sqids-python/blob/main/_autodocs/configuration.md

Use this custom alphabet to randomize the generated IDs. With the given alphabet, the ID for [1, 2, 3] becomes "B4aajs", which differs from the default-alphabet output.

```python
from sqids import Sqids

sqids = Sqids(
    alphabet="FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE"
)
id_ = sqids.encode([1, 2, 3])   # "B4aajs" (differs from the default-alphabet ID)
```
Tokens:
Raw