!squash pr description wip

Author: tony

PR.md

@@ -0,0 +1,121 @@
+# Enhanced Terminal Content Waiting Utility
+
+## Overview
+
+This PR introduces a significant enhancement to the terminal content waiting utility in libtmux. The changes include a more fluent API inspired by Playwright, improved error handling, type checking fixes, and the ability to wait for multiple content patterns.
+
+## Key Features
+
+### 1. Fluent API with Playwright-Inspired Design
+
+```python
+# Before
+result = wait_for_pane_content(pane, "hello world", ContentMatchType.CONTAINS)
+
+# After
+result = expect(pane).wait_for_text("hello world")
+
+# With method chaining
+result = (
+    expect(pane)
+    .with_timeout(5.0)
+    .without_raising()
+    .wait_for_exact_text("completed successfully")
+)
+```
+
+### 2. Multiple Pattern Support
+
+```python
+# Wait for any of these patterns to appear
+result = wait_for_any_content(
+    pane, 
+    ["Success", "Error:", "timeout"], 
+    ContentMatchType.CONTAINS
+)
+if result.success:
+    print(f"Pattern '{result.matched_content}' found at index {result.matched_pattern_index}")
+
+# Wait for all patterns to appear
+result = wait_for_all_content(
+    pane,
+    ["Database connected", "Server started"],
+    ContentMatchType.CONTAINS
+)
+if result.success:
+    for pattern in result.matched_content:
+        print(f"Found pattern: {pattern}")
+```
+
+### 3. Mixed Pattern Types
+
+```python
+# Different match types in a single call
+result = wait_for_any_content(
+    pane,
+    [
+        "exact match",                   # String for exact match
+        "partial text",                  # String for contains match
+        re.compile(r"\d+ items found"),  # Regex pattern
+        lambda lines: len(lines) > 10    # Predicate function
+    ],
+    [
+        ContentMatchType.EXACT,
+        ContentMatchType.CONTAINS,
+        ContentMatchType.REGEX,
+        ContentMatchType.PREDICATE
+    ]
+)
+```
+
+### 4. Performance and Debugging Improvements
+
+- Added elapsed time tracking for timing information
+- Improved error messaging with detailed type checking
+- Fixed return type handling for `wait_for_all_content` to return a list of matched patterns
+
+## Fixed Issues
+
+- Resolved all type checking issues with proper type annotations
+- Fixed inconsistencies between `matched_line` and `match_line` attributes
+- Improved doctest examples to prevent execution failures
+- Resolved timeout message formatting
+
+## Documentation
+
+- Created comprehensive documentation in `docs/test-helpers/waiter.md`
+- Added examples for all usage patterns including the new fluent API
+- Updated API reference with accurate return types
+- Added detailed explanation of the `WaitResult` object properties
+
+## Example Code
+
+- Added example file in `tests/examples/test/test_waiter.py` demonstrating different ways to use the enhanced API
+- Ensured examples follow best practices and appropriate error handling
+
+## Type Checking
+
+- Improved type annotations for better IDE support and static type checking
+- Ensured full mypy compatibility with no type errors
+
+## Testing
+
+- All existing tests pass with no failures
+- Fixed test cases for `wait_for_any_content` and `wait_for_all_content`
+- Added comprehensive tests for the new fluent API methods
+- Made test_wait_until_ready.py more robust with fallback patterns and better error handling
+
+## Recent Improvements
+
+- Fixed linting and formatting issues throughout the waiter module
+- Improved error handling in wait functions with proper else blocks
+- Optimized code for readability and maintainability
+- Added conftest.py to register the example pytest marker
+- Made the shell prompt detection more robust using common prompt characters
+- Added and improved type annotations throughout the codebase
+
+## Documentation
+
+- Updated example code in test_wait_until_ready.py to use contextlib.suppress
+- Made all examples compatible with automated testing and documentation
+- Documentation is now fully synchronized with code examples via literalinclude directives