title_codec

Title encoding/decoding module for folder name serialization.

This module provides functions to validate, encode, and decode titles for use in folder names. The allowed character set is intentionally restricted to ensure cross-platform compatibility and reversible encoding.

Allowed characters in title: a-z, A-Z, 0-9, space

Encoding rules: - Space → Hyphen (-) - Consecutive spaces → Single hyphen - Leading/trailing spaces → Trimmed

Decoding rules: - Hyphen → Space - Invalid characters → Space (then normalized)

exception shai_tix.title_codec.TitleValidationError(title: str, invalid_chars: set[str])

Raised when a title contains invalid characters.

shai_tix.title_codec.validate_title(title: str) → None

Validate that a title contains only allowed characters.

Allowed characters: a-z, A-Z, 0-9, space

Parameters:

title – The title string to validate

Raises:

TitleValidationError – If title contains invalid characters

shai_tix.title_codec.is_valid_title(title: str) → bool

Check if a title contains only allowed characters.

Parameters:

title – The title string to check

Returns:

True if valid, False otherwise

shai_tix.title_codec.encode_title(title: str) → str

Encode a title for use in folder names.

Converts spaces to hyphens. Multiple consecutive spaces become a single hyphen. Leading and trailing spaces are trimmed.

Parameters:

title – The title string to encode (must be valid)

Returns:

Encoded string suitable for folder names

Raises:

TitleValidationError – If title contains invalid characters

shai_tix.title_codec.decode_title(encoded: str) → str

Decode a folder name title back to the original title.

Converts hyphens back to spaces. Any invalid characters encountered (from manual folder editing) are replaced with spaces, then normalized.

Parameters:

encoded – The encoded string from folder name

Returns:

Decoded title with spaces