Waiter 0.1

CHANGES

@@ -34,6 +34,18 @@ $ uvx --from 'libtmux' --prerelease allow python
 
 - _Future release notes will be placed here_
 
+### New features
+
+#### Waiting (#582)
+
+Added experimental `waiter.py` module for polling for terminal content in tmux panes:
+
+- Fluent API inspired by Playwright for better readability and chainable options
+- Support for multiple pattern types (exact text, contains, regex, custom predicates)
+- Composable waiting conditions with `wait_for_any_content` and `wait_for_all_content`
+- Enhanced error handling with detailed timeouts and match information
+- Robust shell prompt detection
+
 ## libtmux 0.47.0 (2025-11-01)
 
 ### Breaking changes
@@ -64,8 +76,8 @@ $ uvx --from 'libtmux' --prerelease allow python
 
 _Maintenance only, no bug fixes or new features_
 
-A version branch has been created at v0.46.x, the next release of v0.47.0 may 
-be a few months in waiting (watchers / snapshots are in development in #587). 
+A version branch has been created at v0.46.x, the next release of v0.47.0 may
+be a few months in waiting (watchers / snapshots are in development in #587).
 
 ### Documentation
 

docs/internals/index.md

@@ -11,6 +11,7 @@ If you need an internal API stabilized please [file an issue](https://github.com
 ```{toctree}
 dataclasses
 query_list
+waiter
 ```
 
 ## Environmental variables

docs/internals/waiter.md

@@ -0,0 +1,135 @@
+(waiter)=
+
+# Waiters - `libtmux._internal.waiter`
+
+The waiter module provides utilities for waiting on specific content to appear in tmux panes, making it easier to write reliable tests that interact with terminal output.
+
+## Key Features
+
+- **Fluent API**: Playwright-inspired chainable API for expressive, readable test code
+- **Multiple Match Types**: Wait for exact matches, substring matches, regex patterns, or custom predicate functions
+- **Composable Waiting**: Wait for any of multiple conditions or all conditions to be met
+- **Flexible Timeout Handling**: Configure timeout behavior and error handling to suit your needs
+- **Shell Prompt Detection**: Easily wait for shell readiness with built-in prompt detection
+- **Robust Error Handling**: Improved exception handling and result reporting
+- **Clean Code**: Well-formatted, linted code with proper type annotations
+
+## Basic Concepts
+
+When writing tests that interact with tmux sessions and panes, it's often necessary to wait for specific content to appear before proceeding with the next step. The waiter module provides a set of functions to help with this.
+
+There are multiple ways to match content:
+- **Exact match**: The content exactly matches the specified string
+- **Contains**: The content contains the specified string
+- **Regex**: The content matches the specified regular expression
+- **Predicate**: A custom function that takes the pane content and returns a boolean
+
+## Quick Start Examples
+
+### Simple Waiting
+
+Wait for specific text to appear in a pane:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_for_text.py
+:language: python
+```
+
+### Advanced Matching
+
+Use regex patterns or custom predicates for more complex matching:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_for_regex.py
+:language: python
+```
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_custom_predicate.py
+:language: python
+```
+
+### Timeout Handling
+
+Control how long to wait and what happens when a timeout occurs:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_timeout_handling.py
+:language: python
+```
+
+### Waiting for Shell Readiness
+
+A common use case is waiting for a shell prompt to appear, indicating the command has completed. The example below uses a regular expression to match common shell prompt characters (`$`, `%`, `>`, `#`):
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_until_ready.py
+:language: python
+```
+
+> Note: This test is skipped in CI environments due to timing issues but works well for local development.
+
+## Fluent API (Playwright-inspired)
+
+For a more expressive and chainable API, you can use the fluent interface provided by the `PaneContentWaiter` class:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_fluent_basic.py
+:language: python
+```
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_fluent_chaining.py
+:language: python
+```
+
+## Multiple Conditions
+
+The waiter module also supports waiting for multiple conditions at once:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_for_any_content.py
+:language: python
+```
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_for_all_content.py
+:language: python
+```
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_mixed_pattern_types.py
+:language: python
+```
+
+## Implementation Notes
+
+### Error Handling
+
+The waiting functions are designed to be robust and handle timing and error conditions gracefully:
+
+- All wait functions properly calculate elapsed time for performance tracking
+- Functions handle exceptions consistently and provide clear error messages
+- Proper handling of return values ensures consistent behavior whether or not raises=True
+
+### Type Safety
+
+The waiter module is fully type-annotated to ensure compatibility with static type checkers:
+
+- All functions include proper type hints for parameters and return values
+- The ContentMatchType enum ensures that only valid match types are used
+- Combined with runtime checks, this prevents type-related errors during testing
+
+### Example Usage in Documentation
+
+All examples in this documentation are actual test files from the libtmux test suite. The examples are included using `literalinclude` directives, ensuring that the documentation remains synchronized with the actual code.
+
+## API Reference
+
+```{eval-rst}
+.. automodule:: libtmux._internal.waiter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource
+```
+
+## Extended Retry Functionality
+
+```{eval-rst}
+.. automodule:: libtmux._internal.retry_extended
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource
+```

pyproject.toml

@@ -127,6 +127,11 @@ files = [
   "tests",
 ]
 
+[[tool.mypy.overrides]]
+module = "tests.examples.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+
 [tool.coverage.run]
 branch = true
 parallel = true

src/libtmux/_internal/retry_extended.py

@@ -0,0 +1,65 @@
+"""Extended retry functionality for libtmux."""
+
+from __future__ import annotations
+
+import logging
+import time
+import typing as t
+
+from libtmux.exc import WaitTimeout
+from libtmux.test.constants import (
+    RETRY_INTERVAL_SECONDS,
+    RETRY_TIMEOUT_SECONDS,
+)
+
+logger = logging.getLogger(__name__)
+
+if t.TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def retry_until_extended(
+    fun: Callable[[], bool],
+    seconds: float = RETRY_TIMEOUT_SECONDS,
+    *,
+    interval: float = RETRY_INTERVAL_SECONDS,
+    raises: bool | None = True,
+) -> tuple[bool, Exception | None]:
+    """
+    Retry a function until a condition meets or the specified time passes.
+
+    Extended version that returns both success state and exception.
+
+    Parameters
+    ----------
+    fun : callable
+        A function that will be called repeatedly until it returns ``True`` or
+        the specified time passes.
+    seconds : float
+        Seconds to retry. Defaults to ``8``, which is configurable via
+        ``RETRY_TIMEOUT_SECONDS`` environment variables.
+    interval : float
+        Time in seconds to wait between calls. Defaults to ``0.05`` and is
+        configurable via ``RETRY_INTERVAL_SECONDS`` environment variable.
+    raises : bool
+        Whether or not to raise an exception on timeout. Defaults to ``True``.
+
+    Returns
+    -------
+    tuple[bool, Exception | None]
+        Tuple containing (success, exception). If successful, the exception will
+        be None.
+    """
+    ini = time.time()
+    exception = None
+
+    while not fun():
+        end = time.time()
+        if end - ini >= seconds:
+            timeout_msg = f"Timed out after {seconds} seconds"
+            exception = WaitTimeout(timeout_msg)
+            if raises:
+                raise exception
+            return False, exception
+        time.sleep(interval)
+    return True, None