hashids-python: Generate YouTube-like Hashes from Numbers

Introduction

`hashids-python` is a robust Python implementation of the popular `hashids` library, designed to generate short, unique, YouTube-like hashes from one or many numbers. Its primary purpose is to obfuscate database IDs, preventing the exposure of their original numeric values to users in public-facing URLs or APIs. This library ensures broad compatibility, supporting Python 2.7 and Python 3.5-3.8, including PyPy environments. It provides a flexible and secure method for handling identifiers when direct numeric exposure is undesirable.

Installation

Installing `hashids-python` is straightforward using pip:

pip install hashids

For compatibility with older `hashids.js 0.1.x` implementations, you can install a specific version:

pip install hashids==0.8.4

Examples

Here are some common ways to use `hashids-python`:

Basic Usage

Import the `Hashids` constructor and encode/decode integers:

from hashids import Hashids
hashids = Hashids()

# Encode a single integer
hashid = hashids.encode(123) # 'Mj3'
print(f"Encoded 123: {hashid}")

# Decode a hash
ints = hashids.decode('xoz') # (456,)
print(f"Decoded 'xoz': {ints}")

# Encode several integers
hashid_multi = hashids.encode(123, 456, 789) # 'El3fkRIo3'
print(f"Encoded 123, 456, 789: {hashid_multi}")

# Decode multiple integers
ints_multi = hashids.decode('1B8UvJfXm') # (517, 729, 185)
print(f"Decoded '1B8UvJfXm': {ints_multi}")

Using A Custom Salt

Adding a unique salt enhances the randomness and makes your hashes harder to guess:

hashids_salt1 = Hashids(salt='this is my salt 1')
hashid_salt1 = hashids_salt1.encode(123) # 'nVB'
print(f"Encoded 123 with salt 1: {hashid_salt1}")

hashids_salt2 = Hashids(salt='this is my salt 2')
hashid_salt2 = hashids_salt2.encode(123) # 'ojK'
print(f"Encoded 123 with salt 2: {hashid_salt2}")

A salt string between 6 and 32 characters provides decent randomization.

Controlling Hash Length

You can specify a minimum hash length to obfuscate the magnitude of the underlying integer:

hashids_min_len = Hashids(min_length=16)
hashid_min_len = hashids_min_len.encode(1) # '4q2VolejRejNmGQB'
print(f"Encoded 1 with min_length 16: {hashid_min_len}")

Using A Custom Alphabet

Customize the characters used in your hashes. For example, to use only lowercase letters:

hashids_alphabet = Hashids(alphabet='abcdefghijklmnopqrstuvwxyz')
hashid_alphabet = hashids_alphabet.encode(123456789) # 'kekmyzyk'
print(f"Encoded 123456789 with custom alphabet: {hashid_alphabet}")

A custom alphabet must contain at least 16 characters.

Why Use hashids-python?

`hashids-python` offers several compelling reasons for its use in applications:

• ID Obfuscation: It effectively hides your database IDs, preventing users from inferring information about your data structure or enumerating records.
• Unguessable Hashes: The algorithm is designed to produce unguessable and unpredictable hashes, even for sequential or repeating numbers, enhancing privacy.
• Readability and Safety: It intelligently avoids generating common English curse words, making the hashes suitable for public display, such as in URLs.
• Flexibility: With options for custom salts, minimum hash lengths, and custom alphabets, you have fine-grained control over the generated hashes.
• Cross-Platform Compatibility: Being a port of the JavaScript `hashids` library, it allows for consistent ID generation across different parts of your tech stack.

While `hashids-python` excels at obfuscation, it's important to remember that it is not designed or tested for cryptographic security purposes.

Links

• GitHub Repository: davidaurelio/hashids-python
• Official hashids Website: hashids.org