Registry / serialization / base32-crockford

base32-crockford

library0.3.0pypypi✓ verified 85d ago

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.

serialization

pip install base32-crockford

github ↗package ↗

INSTALL

IMPORT

SIG · BASE32-CROCKFORD

base32-crockford

serializationpythonv0.3.0

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

base32_crockford

✓ import base32_crockford

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

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}")

Debug

Known issues

gotchaThe 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.

affects: All versions

gotchaChecksum 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.

affects: All versions

gotchaThe `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.

affects: All versions

deprecatedThe 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.

affects: <=0.3.0

Errors

Common errors & fixes

ValueError: Check symbol validation failed

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

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

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')`.

Upgrade

Version history

0.3.0latest on PyPI · released Mar 19, 2015

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jbittel/base32-crockford ↗

packagehttps://pypi.org/project/base32-crockford/ ↗