baseh

Python implementation of the baseH codec. Encodes an internal integer ID as a checksummed, optionally permuted human-readable reference code. Implements the normative spec in ../spec/IMPLEMENTATION_CODEC.md and passes the frozen cross-language vectors in ../vectors/.

Zero runtime dependencies. HMAC-SHA-256 comes from the standard library.

Install

pip install ./python

Or run in place without installing:

PYTHONPATH=python/src python3 -c "import baseh"

Usage

from baseh import Baseh, BasehError, baseh_medium_v1

codec = Baseh(baseh_medium_v1())

code = codec.encode(123456789)
print(code)                       # fixed-length, checksummed code

result = codec.decode(code.lower())  # case-insensitive
print(result.id)                  # 123456789
print(result.canonical_code)      # canonical rendering
print(result.corrected)           # False (input differed only in case)

# Assisted correction over spoken-confusion pairs (B/D, P/T, ...):
fixed = codec.decode(
    code,
    try_correction=True,
    confusion_profile="light",
)

# Non-throwing validation for user input:
check = codec.validate("0000000")
print(check)                      # {"valid": False, "reason": "INVALID_CHECKSUM"}

print(codec.capacity())           # 481890304

Errors raise BasehError with a .code attribute, one of: INVALID_PROFILE, OUT_OF_RANGE, PERMUTATION_FAILURE, INVALID_LENGTH, INVALID_CHARACTER, INVALID_CHECKSUM, AMBIGUOUS_INPUT, TOO_MANY_CANDIDATES, BLOCKED_CODE.

Frozen tiers

Four frozen profiles, each 6 body symbols and case-insensitive, built from the full alphanumeric set with cumulative visual and spoken strips:

Medium is the default. All four keep the typed O/I/L aliases where possible and run the default profanity blocklist. Minimum also uses a hyphen delimiter (XXX-XXX); the rest have none.

Each helper returns a freshly-built mutable profile dict on every call, so callers can load a default and modify it:

profile = baseh_medium_v1()
profile["checksumLength"] = 2
codec = Baseh(profile)

Permuted variants

The _p variants are identical to their tier but enable feistel-v1 permutation and require caller-supplied key material:

from baseh import Baseh, baseh_medium_p_v1

key = bytes.fromhex("746573742d6f6e6c792d6b65792d6d6174657269616c2d30303031")
codec = Baseh(baseh_medium_p_v1(key, key_id="my-app-01"))  # rounds defaults to 8

Available as baseh_minimum_p_v1, baseh_light_p_v1, baseh_medium_p_v1 and baseh_heavy_p_v1.

Profanity safety (spec 18)

All frozen tiers run the default blocklist. Profiles accept a profanity field to change that:

# Block specific words (substrings of the raw code) at encode time:
profile = baseh_medium_v1()
profile["profanity"] = {"mode": "blocklist", "extraWords": ["QQQQ"]}
codec = Baseh(profile)
# codec.encode(id) raises BasehError(code="BLOCKED_CODE") on a match.

# Or remove vowels from both alphabets entirely:
profile["profanity"] = {"mode": "no-vowels"}

Tests

cd python
PYTHONPATH=src python3 -m unittest discover -s tests -v