Douglas Crockford's Base32 Encoding

Common errors

• ValueError: Check symbol validation failed

  cause You attempted to decode a string with a checksum (by passing `checksum=True` to `decode()`), but the checksum character at the end of the string is either missing or does not match the computed checksum of the decoded value.
  fix Ensure that the input string is complete and uncorrupted. If the original string was not encoded with a checksum, remove `checksum=True` from the `decode()` call. If it was, verify the integrity of the string being decoded.

• ValueError: symbol string requires normalization

  cause You called `decode()` or `normalize()` with `strict=True` on an input string that contains characters requiring normalization (e.g., lowercase letters, hyphens, or ambiguous characters like 'O' or 'I' which would be mapped to '0' or '1').
  fix To allow the library to perform automatic normalization, remove the `strict=True` argument. If strict validation is desired, pre-process the input string to conform to uppercase, hyphen-free, and unambiguous character rules before calling `decode(strict=True)`.

• TypeError: an integer is required

  cause The `base32_crockford.encode()` function expects an integer as its primary argument, but you provided a different type, such as a string or bytes object.
  fix Convert the input data to an integer before calling `encode()`. For example, to encode bytes, use `int.from_bytes(my_bytes_object, 'big')`.

Warnings

• gotcha The library automatically normalizes common ambiguous characters (I/L to 1, O to 0) and removes hyphens during decoding by default. While this aligns with Crockford's specification for error resistance, users expecting strict character matching might decode unexpected values if inputs are not precisely formed.
  Fix: If strict input validation is required, use `strict=True` in `decode()` or `normalize()`, but be prepared for `ValueError` if normalization would be needed. Alternatively, pre-normalize with `normalize()` and inspect the result before decoding.
• gotcha Checksum validation is not performed by default during decoding. If a string was encoded with `checksum=True`, you must explicitly pass `checksum=True` to `decode()` to enable validation. Otherwise, a string with an invalid or missing checksum will be decoded without error.
  Fix: Always use `checksum=True` when decoding strings that were originally encoded with a checksum to ensure data integrity.
• gotcha The `encode()` function primarily handles integers, not arbitrary byte strings. Users attempting to encode `bytes` objects directly will encounter a `TypeError`.
  Fix: Convert `bytes` objects to integers before encoding (e.g., using `int.from_bytes(my_bytes, 'big')`) and convert the decoded integer back to bytes (e.g., using `my_integer.to_bytes(length, 'big')`) after decoding.
• deprecated The library's last release (0.3.0) was in March 2015, indicating a lack of active development and maintenance. While functional for its stated purpose, it may not receive updates for new Python versions or security patches.
  Fix: Consider potential long-term maintenance or compatibility risks. For new projects, evaluate more actively maintained alternatives if the core functionality of Crockford's base32 is not strictly required, or if `bytes` encoding/decoding is needed out-of-the-box.

Install

• pip install base32-crockford Install with pip

Imports

• base32_crockford

  import base32_crockford

  The library exposes its functions directly under the top-level module name 'base32_crockford'.

Quickstart

This example demonstrates how to encode and decode integers, use the optional checksum feature, and normalize base32 strings according to Crockford's rules.

import base32_crockford

# Encode an integer
encoded_value = base32_crockford.encode(42)
print(f"Encoded 42: {encoded_value}")

# Decode an encoded string
decoded_value = base32_crockford.decode('1A')
print(f"Decoded '1A': {decoded_value}")

# Encode with checksum
encoded_with_checksum = base32_crockford.encode(1234, checksum=True)
print(f"Encoded 1234 with checksum: {encoded_with_checksum}")

# Decode with checksum validation
decoded_with_checksum = base32_crockford.decode(encoded_with_checksum, checksum=True)
print(f"Decoded '{encoded_with_checksum}' with checksum: {decoded_with_checksum}")

# Normalize a string (e.g., with lowercase or hyphens)
normalized_string = base32_crockford.normalize('lA-O')
print(f"Normalized 'lA-O': {normalized_string}")