Improved option management, add hook management

.github/workflows/tests.yml

@@ -9,6 +9,7 @@ jobs:
 
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ['3.9', '3.13']
         tmux-version: ['2.6', '2.7', '2.8', '3.0a', '3.1b', '3.2a', '3.3a', '3.4', '3.5', 'master']

CHANGES

@@ -15,6 +15,18 @@ $ pip install --user --upgrade --pre libtmux
 
 - _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.46.2 (2025-05-26)
 
 ### Development
@@ -33,8 +45,8 @@ $ pip install --user --upgrade --pre libtmux
 
 _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
 
@@ -221,6 +233,43 @@ Add `TestServer` pytest fixture for creating temporary tmux servers (#565):
 - dev dependencies: Include `typing-extensions` for Python version < 3.11 via
   the `testing` and `lint` groups, via #564.
 
+### Renamed commands
+
+- Renamed `Window.set_window_option()` to {meth}`Window.set_option()` (#516)
+
+  Deprecated `Window.set_window_option()`
+
+- Renamed `Window.show_window_option()` to {meth}`Window.show_option()` (#516)
+
+  Deprecated `Window.show_window_option()`
+
+- Renamed `Window.show_window_options()` to {meth}`Window.show_options()` (#516)
+
+  Deprecated `Window.show_window_options()`
+
+### Improved options
+
+- Option support expanded to server, session, window, and pane
+- Option support enhanced and streamlined via {class}`options.OptionsMixin`.
+
+  - `set_option`
+  - `show_option`
+  - `show_options`
+  - `unset_option`
+
+- {meth}`Window.set_option()` (#516)
+
+  Added arguments:
+
+  - `format` -> `-F`
+  - `unset` -> `-u`
+  - `global` -> `-g`
+  - `unset_panes` -> `-U`: Also unset other panse in windows
+  - `prevent_overwrite`: `-o`
+  - `suppress_warnings`: `-q`
+  - `append`: `-a`
+
+
 ## libtmux 0.42.0 (2025-02-02)
 
 ### Bug fixes
@@ -247,17 +296,6 @@ Add `TestServer` pytest fixture for creating temporary tmux servers (#565):
 - `Server`: Fix `colors` docstring to note it accepts `88` or `256`, Thank you
   @TravisDart! (via #544)
 
-### Development
-
-#### chore: Implement PEP 563 deferred annotation resolution (#555)
-
-- Add `from __future__ import annotations` to defer annotation resolution and reduce unnecessary runtime computations during type checking.
-- Enable Ruff checks for PEP-compliant annotations:
-  - [non-pep585-annotation (UP006)](https://docs.astral.sh/ruff/rules/non-pep585-annotation/)
-  - [non-pep604-annotation (UP007)](https://docs.astral.sh/ruff/rules/non-pep604-annotation/)
-
-For more details on PEP 563, see: https://peps.python.org/pep-0563/
-
 ## libtmux 0.40.1 (2024-12-24)
 
 ### Bug fix

docs/api/hooks.md

@@ -0,0 +1,6 @@
+# Hooks
+
+```{eval-rst}
+.. automodule:: libtmux.hooks
+   :members:
+```

docs/api/index.md

@@ -11,6 +11,8 @@ servers
 sessions
 windows
 panes
+options
+hooks
 constants
 common
 exceptions

docs/api/options.md

@@ -0,0 +1,6 @@
+# Options
+
+```{eval-rst}
+.. automodule:: libtmux.options
+   :members:
+```

docs/internals/constants.md

@@ -0,0 +1,15 @@
+# Internal Constants - `libtmux._internal.constants`
+
+:::{warning}
+Be careful with these! These constants are private, internal as they're **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need a data structure here made public or stabilized please [file an issue](https://github.com/tmux-python/libtmux/issues).
+:::
+
+```{eval-rst}
+.. automodule:: libtmux._internal.constants
+   :members:
+   :undoc-members:
+   :inherited-members:
+   :show-inheritance:
+```

docs/internals/index.md

@@ -11,6 +11,8 @@ If you need an internal API stabilized please [file an issue](https://github.com
 ```{toctree}
 dataclasses
 query_list
+waiter
+constants
 ```
 
 ## 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.test.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