k-hhc 1.1.0

Python bindings for Hexahexacontadecimal (base66) encoding

Python bindings for the k-hhc (Hexahexacontadecimal) C++ library.

This project is intended to be an exploration in creating performant, secure, and portable algorithms, while also being a learning experience for me. Take it with a grain of salt.

Inspired by hexahexacontadecimal by Alexander Ljungberg

Installation

# From the python directory
cd python
pip install .

# Or for development
pip install -e .

Requirements

• Python 3.7+
• C++17 compatible compiler (clang++ recommended)
• pybind11 (build-time only; pulled in automatically by pip/setuptools)

Release build behavior

Release wheels are built with NDEBUG defined. Internal HHC_ASSERT failures do not print a message; they terminate the process via a trap instruction (__builtin_trap). This fail-fast behavior is intentional for release builds.

Usage

Basic Example

import k_hhc

# Encode a 32-bit value
value = 424242
padded = k_hhc.encode_padded_32bit(value)      # Returns: "--.TNv"
unpadded = k_hhc.encode_unpadded_32bit(value)  # Returns: ".TNv"

# Decode a string
decoded = k_hhc.decode_32bit(".TNv")  # Returns: 424242

# 64-bit operations
big_value = 9876543210
padded64 = k_hhc.encode_padded_64bit(big_value)      # Returns: "-----5tVfK4"
unpadded64 = k_hhc.encode_unpadded_64bit(big_value)  # Returns: "5tVfK4"
decoded64 = k_hhc.decode_64bit("5tVfK4")  # Returns: 9876543210

Error Handling

import k_hhc

try:
    # Invalid characters
    k_hhc.decode_32bit("INVALID!")
except ValueError as e:
    print(f"Invalid string: {e}")

try:
    # Value exceeds bounds
    k_hhc.decode_32bit("1QLCp2")  # Exceeds UINT32_MAX
except OverflowError as e:
    print(f"Value too large: {e}")

API Reference

Functions

• encode_padded_32bit(value: int) -> str: Encode a 32-bit integer to a padded 6-character string
• encode_unpadded_32bit(value: int) -> str: Encode a 32-bit integer to an unpadded string
• decode_32bit(encoded: str) -> int: Decode a string to a 32-bit integer
• encode_padded_64bit(value: int) -> str: Encode a 64-bit integer to a padded 11-character string
• encode_unpadded_64bit(value: int) -> str: Encode a 64-bit integer to an unpadded string
• decode_64bit(encoded: str) -> int: Decode a string to a 64-bit integer

Constants

• HHC_32BIT_ENCODED_LENGTH: Length of padded 32-bit encoded strings (6)
• HHC_64BIT_ENCODED_LENGTH: Length of padded 64-bit encoded strings (11)
• HHC_32BIT_STRING_LENGTH: Buffer size for 32-bit encode output (8)
• HHC_64BIT_STRING_LENGTH: Buffer size for 64-bit encode output (16)
• HHC_32BIT_ENCODED_MAX_STRING: Maximum valid padded 32-bit encoded string ("1QLCp1")
• HHC_64BIT_ENCODED_MAX_STRING: Maximum valid padded 64-bit encoded string ("9lH9ebONzYD")
• ALPHABET: The HHC alphabet string (66 characters)

Exceptions

• ValueError: Raised when decoding a string with invalid characters
• OverflowError: Raised when decoding a string that exceeds the bit bounds

Examples

See the examples/ directory for complete examples:

• encode_example.py: Demonstrates encoding functionality
• decode_example.py: Demonstrates decoding with error handling and round-trip tests