Validation & Hooks

Custom button validation rules with ButtonValidator and keyboard construction hooks with KeyboardHookManager.

Button Validation

from pykeyboard.hooks import ButtonValidator

validator = ButtonValidator()

# Rule: button text must be under 64 chars
@validator.rule("max_length")
def check_length(button):
    if len(button.text) > 64:
        return False, "Button text too long (max 64 chars)"
    return True, None

# Rule: callback_data must not contain spaces
@validator.rule("no_spaces")
def check_no_spaces(button):
    if hasattr(button, "callback_data") and " " in (button.callback_data or ""):
        return False, "callback_data cannot contain spaces"
    return True, None

Keyboard Hooks

Hook into the keyboard construction lifecycle:

Hook Type	When	Use Case
`pre_build`	Before keyboard is finalized	Validate row counts, add default buttons
`post_build`	After keyboard is built	Logging, analytics, caching
`button_transform`	On each button during build	Add prefixes, modify callback patterns
`error_hook`	When validation fails	Error reporting, fallback keyboards

Hook manager example

from pykeyboard.hooks import KeyboardHookManager

hooks = KeyboardHookManager()

@hooks.pre_build
def add_back_button(keyboard):
    """Always add a back button as the last row."""
    keyboard.row(InlineButton(text="← Back", callback_data="back"))

@hooks.error_hook
def on_error(error, keyboard):
    print(f"Keyboard build failed: {error}")