base32-crockford

base32-crockford is a small Python module implementing the alternate base32 encoding designed by Douglas Crockford. Unlike standard base32, Crockford’s scheme is optimized to be human and machine readable, compact, error resistant, and pronounceable, using a 32-symbol alphabet that excludes the easily confused letters I, L, O, and U.

The module encodes integers into these symbol strings and decodes them back, transparently normalizing ambiguous characters (i/l to 1, o to 0) and ignoring hyphens used for readability. It can also append and verify a check symbol to detect transcription errors, making it well suited to user-facing identifiers, coupon codes, and short URLs.

What You Get

• encode() to turn an integer into a compact, uppercase Crockford base32 string
• decode() to parse a symbol string back to its integer, normalizing ambiguous characters
• Optional check-symbol generation and verification to catch transcription errors
• Tolerance for hyphens and mixed case so human-typed identifiers decode reliably

Common Use Cases

• Generating short, human-friendly IDs or codes from database integer keys
• Creating error-resistant coupon, invite, or reference codes people type by hand
• Building compact URL slugs that avoid ambiguous characters
• Round-tripping numeric identifiers through a pronounceable, case-insensitive encoding

Under The Hood

Architecture - The library is a single module, base32_crockford.py (about 172 lines). It defines the Crockford symbol alphabet and a separate set of check symbols, along with translation tables that normalize input (mapping I/L to 1 and O to 0, stripping hyphens, upper-casing). encode() repeatedly divides the integer by 32 to build the symbol string and optionally computes a modulo-37 check symbol; decode() reverses the process after normalization and, when requested, validates the trailing check symbol, raising a ValueError on malformed input.

Tech Stack - Pure Python with no third-party runtime dependencies, packaged conventionally with setup.py, setup.cfg, and a MANIFEST. A tox.ini configures multi-version testing.

Code Quality - The module ships a test suite (test.py) exercising encoding, decoding, checksums, and normalization edge cases, with tox for running across Python versions. The code is compact and clearly written, using explicit translation tables rather than ad-hoc conditionals. The project is stable and mature, though it has not seen active development in recent years.

API Design - The public API is two functions plus keyword options (checksum, split), so both basic and checked encoding are one-liners. Inputs are normalized automatically, which keeps caller code simple, and errors surface as ValueError. The README documents the alphabet rules and usage with concise examples.