Add comprehensive type hints and improve error handling

[Abdul-Omira]

Summary

This PR improves code quality by adding comprehensive type hints and fixing error handling issues throughout the codebase.

Changes Made

1. Type Hints Added (utils.py)

• Added type hints to all utility functions: make_safe, exact_div, str2bool, optional_int, optional_float, interpolate_nans
• Added comprehensive docstrings with parameter and return type documentation
• Import statements updated to include necessary type imports

2. Error Handling Improvements

utils.py

• Enhanced exact_div to explicitly check for division by zero
• Improved optional_int and optional_float with proper exception handling and descriptive error messages

vads/pyannote.py

• Fixed resource leak by replacing open(model_fp, 'rb').read() with proper context manager
• Ensures file handles are properly closed even if an exception occurs

alignment.py

• Replaced bare except Exception with specific exceptions: OSError, RuntimeError, KeyError
• Added proper logging instead of print statements
• Exception chaining with from e for better debugging

3. Documentation Improvements (SubtitlesProcessor.py)

• Added class docstring explaining purpose and attributes
• Added type hints to constructor and key methods
• Better parameter documentation

4. Test Suite

• Created comprehensive test suite in test_improvements.py
• Tests cover all modified utility functions
• Validates type hints are properly added
• Verifies error handling improvements

Benefits

1. Better IDE Support: Type hints enable better autocomplete and type checking
2. Reduced Bugs: Specific exception handling prevents silent failures
3. Resource Management: Proper file handling prevents resource leaks
4. Maintainability: Clear documentation and types make code easier to understand
5. Debugging: Better error messages and exception chaining aid in troubleshooting

Testing

All tests pass successfully:

• 10 utility function tests pass
• Type annotation verification passes
• Error handling improvements verified

The test suite demonstrates that all changes work correctly and maintain backward compatibility.

Backward Compatibility

All changes are backward compatible - no breaking changes to existing APIs.