!squash waiter.md doctest

Author: tony

src/libtmux/test/waiter.py

@@ -200,31 +200,39 @@ class PaneContentWaiter:
     >>> hasattr(waiter, 'wait_until_ready')
     True
 
-    .. code-block:: python
-
-        # Real-world usage examples
-        # Basic usage
-        result = PaneContentWaiter(pane).wait_for_text("hello world")
-
-        # With options
-        result = (
-            PaneContentWaiter(pane)
-            .with_timeout(10.0)
-            .wait_for_exact_text("completed successfully")
-        )
-
-        # Wait for regex pattern
-        result = (
-            PaneContentWaiter(pane)
-            .with_timeout(10.0)
-            .wait_for_regex(r"Process \d+ completed")
-        )
-
-        # Custom predicate
-        def is_ready(content):
-            return any("ready" in line.lower() for line in content)
-
-        result = PaneContentWaiter(pane).wait_for_predicate(is_ready)
+    >>> # Real-world usage examples
+    >>> # A functional example: send text to the pane and wait for it
+    >>> # First, send "hello world" to the pane
+    >>> pane.send_keys("echo 'hello world'", enter=True)
+    >>>
+    >>> # Then wait for it to appear in the pane content
+    >>> result = PaneContentWaiter(pane).wait_for_text("hello world")
+    >>> result.success
+    True
+    >>> "hello world" in result.matched_content
+    True
+    >>>
+    >>> # Basic usage (showing API only, other examples)
+    >>> # result = PaneContentWaiter(pane).wait_for_text("other example")
+    >>>
+    >>> # With options
+    >>> # result = (
+    >>> #     PaneContentWaiter(pane)
+    >>> #     .with_timeout(10.0)
+    >>> #     .wait_for_exact_text("completed successfully")
+    >>> # )
+    >>>
+    >>> # Wait for regex pattern
+    >>> # result = (
+    >>> #     PaneContentWaiter(pane)
+    >>> #     .with_timeout(10.0)
+    >>> #     .wait_for_regex(r"Process \d+ completed")
+    >>> # )
+    >>>
+    >>> # Custom predicate
+    >>> def is_ready(content):
+    ...     return any("ready" in line.lower() for line in content)
+    >>> # result = PaneContentWaiter(pane).wait_for_predicate(is_ready)
     """
 
     def __init__(self, pane: Pane) -> None:
@@ -455,22 +463,29 @@ def expect(pane: Pane) -> PaneContentWaiter:
     >>> type(expect(pane)) == type(PaneContentWaiter(pane))  # Same class
     True
 
-    .. code-block:: python
-
-        # Real-world usage examples
-        # Wait for text with a longer timeout
-        result = (
-            expect(pane)
-            .with_timeout(10.0)
-            .wait_for_text("Operation completed")
-        )
-
-        # Wait for a regex match without raising exceptions on timeout
-        result = (
-            expect(pane)
-            .without_raising()
-            .wait_for_regex(r"Process \d+ completed")
-        )
+    >>> # A functional example showing actual usage
+    >>> # Send a command to the pane
+    >>> pane.send_keys("echo 'testing expect'", enter=True)
+    >>>
+    >>> # Wait for the output using the expect function
+    >>> result = expect(pane).wait_for_text("testing expect")
+    >>> result.success
+    True
+    >>>
+    >>> # Real-world usage examples (showing API only, not executed)
+    >>> # Wait for text with a longer timeout
+    >>> # result = (
+    >>> #     expect(pane)
+    >>> #     .with_timeout(10.0)
+    >>> #     .wait_for_text("Operation completed")
+    >>> # )
+    >>>
+    >>> # Wait for a regex match without raising exceptions on timeout
+    >>> # result = (
+    >>> #     expect(pane)
+    >>> #     .without_raising()
+    >>> #     .wait_for_regex(r"Process \d+ completed")
+    >>> # )
     """
     return PaneContentWaiter(pane)
 
@@ -569,37 +584,35 @@ def wait_for_pane_content(
     >>> isinstance(result_pred, WaitResult)
     True
 
-    .. code-block:: python
-
-        # Real-world usage examples
-        # Wait for a $ shell prompt
-        result = wait_for_pane_content(pane, "$", ContentMatchType.CONTAINS)
-
-        # Wait for exact text
-        result = wait_for_pane_content(
-            pane,
-            "Success",
-            ContentMatchType.EXACT,
-            timeout=10.0
-        )
-
-        # Use regex pattern matching
-        import re
-        result = wait_for_pane_content(
-            pane,
-            re.compile(r"Error: .*"),
-            ContentMatchType.REGEX
-        )
-
-        # Use custom predicate function
-        def has_at_least_3_lines(content):
-            return len(content) >= 3
-
-        result = wait_for_pane_content(
-            pane,
-            has_at_least_3_lines,
-            ContentMatchType.PREDICATE
-        )
+    >>> # Real-world usage examples (showing API only, not executed)
+    >>> # Wait for a $ shell prompt
+    >>> # result = wait_for_pane_content(pane, "$", ContentMatchType.CONTAINS)
+    >>>
+    >>> # Wait for exact text
+    >>> # result = wait_for_pane_content(
+    >>> #     pane,
+    >>> #     "Success",
+    >>> #     ContentMatchType.EXACT,
+    >>> #     timeout=10.0
+    >>> # )
+    >>>
+    >>> # Use regex pattern matching
+    >>> import re
+    >>> # result = wait_for_pane_content(
+    >>> #     pane,
+    >>> #     re.compile(r"Error: .*"),
+    >>> #     ContentMatchType.REGEX
+    >>> # )
+    >>>
+    >>> # Use custom predicate function
+    >>> def has_at_least_3_lines(content):
+    ...     return len(content) >= 3
+    >>>
+    >>> # result = wait_for_pane_content(
+    >>> #     pane,
+    >>> #     has_at_least_3_lines,
+    >>> #     ContentMatchType.PREDICATE
+    >>> # )
     """
     result = WaitResult(success=False)
 
@@ -974,35 +987,34 @@ def wait_for_any_content(
 
     Examples
     --------
-    .. code-block:: python
-
-        # Wait for any of the specified patterns
-        result = wait_for_any_content(
-            pane,
-            ["pattern1", "pattern2"],
-            ContentMatchType.CONTAINS
-        )
-
-        # Wait for any of the specified regex patterns
-        import re
-        result = wait_for_any_content(
-            pane,
-            [re.compile(r"Error: .*"), re.compile(r"Success: .*")],
-            ContentMatchType.REGEX
-        )
-
-        # Wait for any of the specified predicate functions
-        def has_at_least_3_lines(content):
-            return len(content) >= 3
-
-        def has_at_least_5_lines(content):
-            return len(content) >= 5
-
-        result = wait_for_any_content(
-            pane,
-            [has_at_least_3_lines, has_at_least_5_lines],
-            ContentMatchType.PREDICATE
-        )
+    >>> # Example patterns for wait_for_any_content (showing API only, not executed)
+    >>> # Wait for any of the specified patterns
+    >>> # result = wait_for_any_content(
+    >>> #     pane,
+    >>> #     ["pattern1", "pattern2"],
+    >>> #     ContentMatchType.CONTAINS
+    >>> # )
+    >>>
+    >>> # Wait for any of the specified regex patterns
+    >>> import re
+    >>> # result = wait_for_any_content(
+    >>> #     pane,
+    >>> #     [re.compile(r"Error: .*"), re.compile(r"Success: .*")],
+    >>> #     ContentMatchType.REGEX
+    >>> # )
+    >>>
+    >>> # Wait for any of the specified predicate functions
+    >>> def has_at_least_3_lines(content):
+    ...     return len(content) >= 3
+    >>>
+    >>> def has_at_least_5_lines(content):
+    ...     return len(content) >= 5
+    >>>
+    >>> # result = wait_for_any_content(
+    >>> #     pane,
+    >>> #     [has_at_least_3_lines, has_at_least_5_lines],
+    >>> #     ContentMatchType.PREDICATE
+    >>> # )
     """
     if not content_patterns:
         msg = "At least one content pattern must be provided"
@@ -1172,35 +1184,34 @@ def wait_for_all_content(
 
     Examples
     --------
-    .. code-block:: python
-
-        # Wait for all of the specified patterns
-        result = wait_for_all_content(
-            pane,
-            ["pattern1", "pattern2"],
-            ContentMatchType.CONTAINS
-        )
-
-        # Wait for all of the specified regex patterns
-        import re
-        result = wait_for_all_content(
-            pane,
-            [re.compile(r"Error: .*"), re.compile(r"Success: .*")],
-            ContentMatchType.REGEX
-        )
-
-        # Wait for all of the specified predicate functions
-        def has_at_least_3_lines(content):
-            return len(content) >= 3
-
-        def has_at_least_5_lines(content):
-            return len(content) >= 5
-
-        result = wait_for_all_content(
-            pane,
-            [has_at_least_3_lines, has_at_least_5_lines],
-            ContentMatchType.PREDICATE
-        )
+    >>> # Example patterns for wait_for_all_content (showing API only, not executed)
+    >>> # Wait for all of the specified patterns
+    >>> # result = wait_for_all_content(
+    >>> #     pane,
+    >>> #     ["pattern1", "pattern2"],
+    >>> #     ContentMatchType.CONTAINS
+    >>> # )
+    >>>
+    >>> # Wait for all of the specified regex patterns
+    >>> import re
+    >>> # result = wait_for_all_content(
+    >>> #     pane,
+    >>> #     [re.compile(r"Error: .*"), re.compile(r"Success: .*")],
+    >>> #     ContentMatchType.REGEX
+    >>> # )
+    >>>
+    >>> # Wait for all of the specified predicate functions
+    >>> def has_at_least_3_lines(content):
+    ...     return len(content) >= 3
+    >>>
+    >>> def has_at_least_5_lines(content):
+    ...     return len(content) >= 5
+    >>>
+    >>> # result = wait_for_all_content(
+    >>> #     pane,
+    >>> #     [has_at_least_3_lines, has_at_least_5_lines],
+    >>> #     ContentMatchType.PREDICATE
+    >>> # )
     """
     if not content_patterns:
         msg = "At least one content pattern must be provided"