{"id":7039,"library":"base32-crockford","title":"Douglas Crockford's Base32 Encoding","description":"base32-crockford is a Python library that implements Douglas Crockford's base32 encoding scheme. This scheme is designed for human and machine readability, compactness, error resistance, and pronounceability. The library is currently at version 0.3.0, released in 2015, suggesting a maintenance-only release cadence.","status":"maintenance","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/jbittel/base32-crockford","tags":["base32","crockford","encoding","decoding","utility","human-readable"],"install":[{"cmd":"pip install base32-crockford","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The library exposes its functions directly under the top-level module name 'base32_crockford'.","symbol":"base32_crockford","correct":"import base32_crockford"}],"quickstart":{"code":"import base32_crockford\n\n# Encode an integer\nencoded_value = base32_crockford.encode(42)\nprint(f\"Encoded 42: {encoded_value}\")\n\n# Decode an encoded string\ndecoded_value = base32_crockford.decode('1A')\nprint(f\"Decoded '1A': {decoded_value}\")\n\n# Encode with checksum\nencoded_with_checksum = base32_crockford.encode(1234, checksum=True)\nprint(f\"Encoded 1234 with checksum: {encoded_with_checksum}\")\n\n# Decode with checksum validation\ndecoded_with_checksum = base32_crockford.decode(encoded_with_checksum, checksum=True)\nprint(f\"Decoded '{encoded_with_checksum}' with checksum: {decoded_with_checksum}\")\n\n# Normalize a string (e.g., with lowercase or hyphens)\nnormalized_string = base32_crockford.normalize('lA-O')\nprint(f\"Normalized 'lA-O': {normalized_string}\")","lang":"python","description":"This example demonstrates how to encode and decode integers, use the optional checksum feature, and normalize base32 strings according to Crockford's rules."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `checksum=True` when decoding strings that were originally encoded with a checksum to ensure data integrity.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `encode()` function primarily handles integers, not arbitrary byte strings. Users attempting to encode `bytes` objects directly will encounter a `TypeError`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<=0.3.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ValueError: Check symbol validation failed"},{"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)`.","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').","error":"ValueError: symbol string requires normalization"},{"fix":"Convert the input data to an integer before calling `encode()`. For example, to encode bytes, use `int.from_bytes(my_bytes_object, 'big')`.","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.","error":"TypeError: an integer is required"}]}