Pyphen

import pyphen

from pyphen import Pyphen, LANGUAGES, language_fallback

import pyphen

# Create hyphenation instance for a language
dic = pyphen.Pyphen(lang='en_US')

# Get word with hyphens inserted at all valid positions
hyphenated = dic.inserted('hyphenation')
print(hyphenated)  # 'hy-phen-ation'

# Iterate through all possible hyphenation splits
for first_part, second_part in dic.iterate('hyphenation'):
    print(f"{first_part} | {second_part}")
# Output:
# hyphena | tion
# hyphen | ation  
# hy | phenation

# Wrap word to fit within specific width
wrapped = dic.wrap('hyphenation', width=8)
if wrapped:
    first, second = wrapped
    print(f"{first} {second}")  # 'hyphen- ation'

# Find all valid hyphenation positions
positions = dic.positions('hyphenation')
print(positions)  # [2, 6, 8] (DataInt objects)

LANGUAGES: dict[str, Path]  # { .api }

def language_fallback(language: str) -> str | None:
    """
    Get a fallback language available in dictionaries using Unicode locale inheritance.
    
    Args:
        language (str): Language code with potential region/script variants (e.g., 'en-US', 'sr-Latn')
    
    Returns:
        str | None: Available language code in LANGUAGES, or None if no fallback found
    """

class Pyphen:
    def __init__(
        self, 
        filename: str | Path | None = None, 
        lang: str | None = None, 
        left: int = 2, 
        right: int = 2, 
        cache: bool = True
    ):
        """
        Create hyphenation instance for specified language or dictionary file.
        
        Args:
            filename (str | Path, optional): Path to custom hyph_*.dic file
            lang (str, optional): Language code for built-in dictionary  
            left (int): Minimum characters in first syllable (default: 2)
            right (int): Minimum characters in last syllable (default: 2)
            cache (bool): Whether to cache hyphenation patterns (default: True)
        
        Raises:
            KeyError: If specified language is not available in LANGUAGES
        """

def positions(self, word: str) -> list[DataInt]:
    """
    Get valid hyphenation positions in word, respecting left/right constraints.
    
    Args:
        word (str): Word to find hyphenation positions for
    
    Returns:
        list[DataInt]: Positions where word can be hyphenated. Each DataInt may contain 
                       tuple (change, index, cut) for non-standard hyphenation patterns.
    """

def iterate(self, word: str) -> Generator[tuple[str, str], None, None]:
    """
    Iterate over all hyphenation possibilities, longest first part first.
    
    Args:
        word (str): Word to hyphenate
    
    Yields:
        tuple[str, str]: (first_part, second_part) for each valid hyphenation point
    """

def __call__(self, word: str) -> Generator[tuple[str, str], None, None]:
    """Alias for iterate() method - makes Pyphen instances callable."""

def wrap(self, word: str, width: int, hyphen: str = '-') -> tuple[str, str] | None:
    """
    Get longest possible first part and remaining part that fits within width.
    
    Args:
        word (str): Word to wrap
        width (int): Maximum length for first part including hyphen
        hyphen (str): Hyphen character to use (default: '-')
    
    Returns:
        tuple[str, str] | None: (first_part_with_hyphen, remaining_part) or None 
                                if no valid hyphenation fits within width
    """

def inserted(self, word: str, hyphen: str = '-') -> str:
    """
    Get word with all possible hyphens inserted at valid positions.
    
    Args:
        word (str): Word to hyphenate
        hyphen (str): Hyphen character to insert (default: '-')
    
    Returns:
        str: Word with hyphens inserted at all valid hyphenation points
    """

class DataInt(int):
    """
    Integer with additional data attribute for hyphenation metadata.
    
    Attributes:
        data (tuple[str, int, int] | None): Non-standard hyphenation data containing
                                           (change, index, cut) for character substitutions
    """
    
    def __new__(cls, value: int, data: tuple[str, int, int] | None = None, reference: DataInt | None = None) -> DataInt:
        """
        Create DataInt with optional hyphenation metadata.
        
        Args:
            value (int): Integer value (hyphenation position)
            data (tuple, optional): Hyphenation metadata (change, index, cut)
            reference (DataInt, optional): Copy data from another DataInt
        """

import pyphen

# List all available language codes  
print(list(pyphen.LANGUAGES.keys()))

# Check if language is available
if 'de_DE' in pyphen.LANGUAGES:
    dic = pyphen.Pyphen(lang='de_DE')
    
# Use fallback for unavailable variants
fallback = pyphen.language_fallback('de-AT-x-variant')  # Returns 'de_AT'

from pathlib import Path
import pyphen

# Load from file path
custom_dict = Path('/path/to/custom_hyph.dic')
dic = pyphen.Pyphen(filename=custom_dict)

# Use existing dictionary path
dic = pyphen.Pyphen(filename=pyphen.LANGUAGES['fr'])

import pyphen

# Default: minimum 2 characters on each side
dic = pyphen.Pyphen(lang='en_US')
print(dic.inserted('automatic'))  # 'au-to-mat-ic'

# Require 4 characters at start, 3 at end
dic = pyphen.Pyphen(lang='en_US', left=4, right=3)  
print(dic.inserted('automatic'))  # 'auto-matic'

# No constraints (left=1, right=1)
dic = pyphen.Pyphen(lang='en_US', left=1, right=1)
print(dic.inserted('automatic'))  # 'a-u-t-o-m-a-t-i-c'

import pyphen

# Hungarian example with character changes
dic = pyphen.Pyphen(lang='hu', left=1, right=1)
word = 'kulissza'

# Standard positions show metadata
for pos in dic.positions(word):
    if pos.data:
        change, index, cut = pos.data
        print(f"Position {pos}: change '{change}' at index {index}, cut {cut}")

# Iteration handles substitutions automatically
for first, second in dic.iterate(word):
    print(f"{first} | {second}")
# Output:
# kulisz | sza     # 'ss' becomes 'sz' + 's'  
# ku | lissza

# Inserted form shows final result
print(dic.inserted(word))  # 'ku-lisz-sza'

import pyphen

# First instance loads and caches dictionary
dic1 = pyphen.Pyphen(lang='en_US')  # Loads dictionary

# Subsequent instances reuse cached dictionary  
dic2 = pyphen.Pyphen(lang='en_US')  # Uses cached dictionary

# Disable caching if needed (e.g., for memory-constrained environments)
dic3 = pyphen.Pyphen(lang='en_US', cache=False)  # Reloads dictionary

import pyphen

# Handle unavailable languages
try:
    dic = pyphen.Pyphen(lang='unknown_language')
except KeyError as e:
    print(f"Language not available: {e}")
    # Use fallback or default language
    dic = pyphen.Pyphen(lang='en_US')

# Handle custom dictionary file errors
try:
    dic = pyphen.Pyphen(filename='/nonexistent/path.dic')
except (FileNotFoundError, PermissionError, UnicodeDecodeError) as e:
    print(f"Dictionary file error: {e}")
    # Fallback to built-in dictionary
    dic = pyphen.Pyphen(lang='en_US')