[Reverted] Waiter 0.1 by tony · Pull Request #582 · tmux-python/libtmux

tony · 2025-02-26T14:53:08Z

Note

Retracted, see Waiter 0.1 #594

sourcery-ai · 2025-02-26T14:53:12Z

Reviewer's Guide by Sourcery

This pull request enhances the terminal content waiting utility by introducing a more fluent API, improved error handling, and support for multiple content patterns. It also includes comprehensive documentation and examples to demonstrate the new features.

Sequence diagram for wait_for_pane_content with regex

sequenceDiagram
    participant User
    participant PaneContentWaiter
    participant Pane
    participant re

    User->>PaneContentWaiter: wait_for_pane_content(pane, pattern, ContentMatchType.REGEX, ...)
    PaneContentWaiter->>Pane: capture_pane(start, end)
    Pane->>Pane: Get content
    Pane-->>PaneContentWaiter: content: list[str]
    alt pattern is str
        PaneContentWaiter->>re: compile(pattern)
        re-->>PaneContentWaiter: regex: re.Pattern
    end
    PaneContentWaiter->>re: search(content_str)
    re-->>PaneContentWaiter: match: Match[str] | None
    alt match is not None
        PaneContentWaiter->>PaneContentWaiter: result.matched_content = match.group(0)
        PaneContentWaiter->>PaneContentWaiter: Find matching line
        PaneContentWaiter-->>User: WaitResult(success=True, ...)
    else match is None
        PaneContentWaiter-->>User: WaitResult(success=False, ...)
    end

Sequence diagram for fluent API usage

sequenceDiagram
    participant User
    participant expect(pane)
    participant PaneContentWaiter
    participant wait_for_text
    participant wait_for_pane_content
    participant Pane

    User->>expect(pane): expect(pane)
    activate expect(pane)
    expect(pane)->>PaneContentWaiter: PaneContentWaiter(pane)
    activate PaneContentWaiter
    expect(pane)-->>User: PaneContentWaiter instance
    deactivate expect(pane)

    User->>PaneContentWaiter: with_timeout(timeout)
    PaneContentWaiter->>PaneContentWaiter: self.timeout = timeout
    PaneContentWaiter-->>User: PaneContentWaiter instance

    User->>PaneContentWaiter: wait_for_text(text)
    activate wait_for_text
    wait_for_text->>wait_for_pane_content: wait_for_pane_content(pane, text, ContentMatchType.CONTAINS, timeout=self.timeout, ...)
    activate wait_for_pane_content
    wait_for_pane_content->>Pane: capture_pane()
    Pane-->>wait_for_pane_content: content
    wait_for_pane_content->>wait_for_pane_content: Check content for text
    alt text found in content
        wait_for_pane_content-->>wait_for_text: WaitResult(success=True, ...)
    else text not found in content
        wait_for_pane_content-->>wait_for_text: WaitResult(success=False, ...)
    end
    deactivate wait_for_pane_content
    wait_for_text-->>User: WaitResult
    deactivate wait_for_text
    deactivate PaneContentWaiter

Updated class diagram for PaneContentWaiter

classDiagram
    class PaneContentWaiter {
        -pane: Pane
        -timeout: float
        -interval: float
        -raises: bool
        -start_line: int | None
        -end_line: int | None
        __init__(pane: Pane) : void
        +with_timeout(timeout: float) : PaneContentWaiter
        +with_interval(interval: float) : PaneContentWaiter
        +without_raising() : PaneContentWaiter
        +with_line_range(start: int | str | None, end: int | str | None) : PaneContentWaiter
        +wait_for_text(text: str) : WaitResult
        +wait_for_exact_text(text: str) : WaitResult
        +wait_for_regex(pattern: str | re.Pattern[str]) : WaitResult
        +wait_for_predicate(predicate: Callable[[list[str]], bool]) : WaitResult
        +wait_until_ready(shell_prompt: str | re.Pattern[str] | None) : WaitResult
    }

    class WaitResult {
        +success: bool
        +content: list[str] | None
        +matched_content: str | list[str] | None
        +match_line: int | None
        +elapsed_time: float | None
        +error: str | None
        +matched_pattern_index: int | None
    }

    class ContentMatchType {
        <<enumeration>>
        EXACT
        CONTAINS
        REGEX
        PREDICATE
    }

    PaneContentWaiter -- WaitResult : Returns
    PaneContentWaiter -- ContentMatchType : Uses

File-Level Changes

Change	Details	Files
Introduces a fluent API for waiting on pane content, inspired by Playwright, allowing method chaining for better readability.	Adds the `PaneContentWaiter` class to encapsulate waiting logic. Adds the `expect` function as a convenient entry point for the fluent API. Implements methods like `with_timeout`, `with_interval`, `without_raising`, and `with_line_range` for configuring the waiter. Implements `wait_for_text`, `wait_for_exact_text`, `wait_for_regex`, `wait_for_predicate`, and `wait_until_ready` methods for performing the actual waiting.	`src/libtmux/_internal/waiter.py` `tests/_internal/test_waiter.py`
Adds support for waiting for multiple content patterns, including the ability to wait for any or all of the specified patterns.	Introduces the `wait_for_any_content` function to wait for any of multiple patterns. Introduces the `wait_for_all_content` function to wait for all of multiple patterns. Updates the `WaitResult` dataclass to include a `matched_pattern_index` attribute for `wait_for_any_content`. Adds comprehensive tests for both `wait_for_any_content` and `wait_for_all_content`.	`src/libtmux/_internal/waiter.py` `tests/_internal/test_waiter.py`
Enables the use of mixed pattern types, allowing different match types (exact, contains, regex, predicate) in a single call.	Modifies `wait_for_any_content` and `wait_for_all_content` to accept a list of `ContentMatchType` values. Adds type checking to ensure that the pattern type is compatible with the match type. Adds tests to verify that mixed pattern types work correctly.	`src/libtmux/_internal/waiter.py` `tests/_internal/test_waiter.py`
Improves error handling with detailed type checking.	Adds specific error messages for invalid pattern types in `wait_for_pane_content`, `wait_for_any_content`, and `wait_for_all_content`. Adds type checking to ensure that the pattern type is compatible with the match type. Adds tests to verify that type errors are raised correctly.	`src/libtmux/_internal/waiter.py` `tests/_internal/test_waiter.py`
Adds elapsed time tracking for timing information.	Adds `elapsed_time` to the `WaitResult` dataclass. Updates `wait_for_pane_content`, `wait_for_any_content`, and `wait_for_all_content` to calculate and store the elapsed time. Adds tests to verify that the elapsed time is calculated correctly.	`src/libtmux/_internal/waiter.py` `tests/_internal/test_waiter.py`
Improves type annotations for better IDE support and static type checking.	Adds type hints to all functions and methods in the `waiter` module. Uses `t.TYPE_CHECKING` to avoid circular imports. Adds mypy overrides for test examples.	`src/libtmux/_internal/waiter.py` `tests/_internal/test_waiter.py` `pyproject.toml`
Creates comprehensive documentation.	Creates a new documentation page for the waiter module. Adds examples for all usage patterns, including the new fluent API. Updates the API reference with accurate return types. Adds a detailed explanation of the `WaitResult` object properties. Updates example code in `test_wait_until_ready.py` to use `contextlib.suppress`. Makes all examples compatible with automated testing and documentation. Ensures documentation is now fully synchronized with code examples via `literalinclude` directives.	`docs/internals/waiter.md` `docs/internals/index.md` `tests/examples/_internal/waiter/test_wait_until_ready.py`
Adds an example file demonstrating different ways to use the enhanced API.	Creates a new example file in `tests/examples/test/test_waiter.py`. Ensures examples follow best practices and appropriate error handling. Adds examples showing how to properly handle timeouts.	`tests/examples/test/test_waiter.py`
Fixes linting and formatting issues throughout the waiter module.	Runs `ruff format` on the `waiter` module. Addresses any linting errors reported by `ruff check`.	`src/libtmux/_internal/waiter.py`
Makes the shell prompt detection more robust using common prompt characters.	Updates the `wait_until_pane_ready` function to use a more robust shell prompt detection mechanism. Uses common prompt characters such as `$`, `%`, `>`, and `#` to identify the shell prompt.	`src/libtmux/_internal/waiter.py` `tests/_internal/test_waiter.py`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!
Generate a plan of action for an issue: Comment @sourcery-ai plan on
an issue to generate a plan of action for it.

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

codecov · 2025-02-26T15:49:58Z

Codecov Report

Attention: Patch coverage is 87.79070% with 63 lines in your changes missing coverage. Please review.

Project coverage is 81.56%. Comparing base (76326f3) to head (50081b5).
Report is 12 commits behind head on master.

Files with missing lines	Patch %	Lines
src/libtmux/_internal/waiter.py	86.37%	22 Missing and 22 partials ⚠️
...examples/_internal/waiter/test_wait_until_ready.py	42.10%	11 Missing ⚠️
tests/examples/_internal/waiter/helpers.py	36.36%	7 Missing ⚠️
...mples/_internal/waiter/test_mixed_pattern_types.py	93.75%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #582      +/-   ##
==========================================
+ Coverage   79.83%   81.56%   +1.73%     
==========================================
  Files          22       37      +15     
  Lines        1914     2430     +516     
  Branches      294      368      +74     
==========================================
+ Hits         1528     1982     +454     
- Misses        266      307      +41     
- Partials      120      141      +21

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

tony · 2025-02-26T20:24:32Z

@sourcery-ai review

sourcery-ai

Hey @tony - I've reviewed your changes - here's some feedback:

Overall Comments:

Consider adding a helper function to reduce duplication in tests that involve sending commands to a pane and waiting for a result.
The new fluent API looks great, but ensure that the documentation clearly explains when to use the fluent API vs. the existing functions.

Here's what I looked at during the review

🟢 General issues: all looks good
🟢 Security: all looks good
🟡 Testing: 3 issues found
🟢 Complexity: all looks good
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

tests/test/test_waiter.py

src/libtmux/test/retry_extended.py

src/libtmux/test/waiter.py

tests/test/test_waiter.py

tony · 2025-02-27T00:30:21Z

@sourcery-ai dismiss

tony · 2025-02-27T15:28:44Z

@sourcery-ai review

sourcery-ai

Hey @tony - I've reviewed your changes - here's some feedback:

Overall Comments:

Consider adding a helper function to encapsulate the logic for creating a new window and pane, as this pattern is repeated throughout the tests.
The addition of the waiter module and its tests is a significant enhancement, but it also adds complexity. Ensure that the documentation is comprehensive and easy to understand for new contributors.

Here's what I looked at during the review

🟡 General issues: 2 issues found
🟢 Security: all looks good
🟡 Testing: 5 issues found
🟡 Complexity: 1 issue found
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

src/libtmux/_internal/waiter.py

tests/_internal/test_waiter.py

docs/internals/waiter.md

src/libtmux/_internal/waiter.py

tests/_internal/test_waiter.py

sourcery-ai

Hey @tony - I've reviewed your changes - here's some feedback:

Overall Comments:

Consider adding a helper function to encapsulate the logic for creating a new window and pane, as this pattern is repeated throughout the tests.
The addition of the waiter module and its tests is a significant enhancement, but it also adds complexity. Ensure that the documentation is comprehensive and easy to understand for new contributors.

Here's what I looked at during the review

🟢 General issues: all looks good
🟢 Security: all looks good
🟡 Testing: 2 issues found
🟡 Complexity: 1 issue found
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

tests/_internal/test_waiter.py

src/libtmux/_internal/waiter.py

tests/_internal/test_waiter.py

tony · 2025-02-27T15:35:03Z

@sourcery-ai plan

tony · 2025-02-27T18:15:50Z

@sourcery-ai review

sourcery-ai

Hey @tony - I've reviewed your changes - here's some feedback:

Overall Comments:

Consider adding a helper function to encapsulate the logic for creating and cleaning up test windows and panes to reduce code duplication across tests.
The new waiter module introduces a lot of new code - consider adding a diagram or high-level overview to the documentation to help users understand the different components and how they fit together.

Here's what I looked at during the review

🟢 General issues: all looks good
🟢 Security: all looks good
🟡 Testing: 1 issue found
🟡 Complexity: 1 issue found
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

tests/_internal/test_waiter.py

src/libtmux/_internal/waiter.py

tests/_internal/test_waiter.py

tony · 2025-02-27T18:24:11Z

@sourcery-ai review

…essaging - Add descriptive timeout message to WaitTimeout exception - Ensure consistent handling of timeout errors - Fix type hints for function return values

…I and multi-pattern support - Implement Playwright-inspired fluent API for more expressive test code - Add wait_for_any_content and wait_for_all_content for composable waiting - Fix type annotations for all wait_for functions - Improve WaitResult class to handle different return types - Fix doctest examples to prevent execution failures - Enhance error handling with better timeout messages

- Fix test_wait_for_pane_content_exact to use correct match type - Update test_wait_for_any_content to check matched_pattern_index - Fix test_wait_for_all_content to handle list of matched patterns - Add comprehensive type annotations to all test functions - Ensure proper handling of None checks for Pane objects

…iters - Create detailed markdown documentation in docs/test-helpers/waiter.md - Add key features section highlighting main capabilities - Include quick start examples for all functions - Document fluent API with Playwright-inspired design - Explain wait_for_any_content and wait_for_all_content with practical examples - Add detailed API reference for all waiters - Include testing best practices section

- Adds a conftest.py file in tests/examples to register the pytest.mark.example marker - Eliminates pytest warnings about unknown markers in example tests - Improves test output by removing noise from warnings

- Each test file focuses on a single feature or concept of the waiter module - Added descriptive docstrings to all test functions for better documentation - Created conftest.py with session fixture for waiter examples - Added helpers.py with utility functions for the test examples - Test files now follow a consistent naming convention for easier reference - Each test file is self-contained and demonstrates a single concept - All tests are marked with @pytest.mark.example for filtering This restructuring supports the documentation update to use literalinclude directives, making the documentation more maintainable and ensuring it stays in sync with actual code.

tony · 2025-02-27T18:39:44Z

@sourcery-ai review

sourcery-ai

Hey @tony - I've reviewed your changes - here's some feedback:

Overall Comments:

Consider adding a helper function to encapsulate the logic for killing windows safely, to avoid repetition in test cleanup.
The addition of comprehensive tests and examples is great, but ensure that these are also regularly reviewed and updated to reflect any API changes.

Here's what I looked at during the review

🟢 General issues: all looks good
🟢 Security: all looks good
🟡 Testing: 1 issue found
🟡 Complexity: 1 issue found
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

tests/examples/_internal/waiter/test_fluent_chaining.py

src/libtmux/_internal/waiter.py

tests/_internal/test_waiter.py

tony force-pushed the waiter-2.0 branch 2 times, most recently from cd876dc to f155d15 Compare February 26, 2025 15:34

tony force-pushed the waiter-2.0 branch from ca98248 to af1e013 Compare February 26, 2025 15:52

sourcery-ai bot reviewed Feb 26, 2025

View reviewed changes

tony force-pushed the waiter-2.0 branch from 0597a7e to 91cb295 Compare February 27, 2025 00:16

tony force-pushed the waiter-2.0 branch 10 times, most recently from 7c755e7 to 9213b88 Compare February 27, 2025 15:27

tony marked this pull request as ready for review February 27, 2025 15:28

sourcery-ai bot reviewed Feb 27, 2025

View reviewed changes

tests/_internal/test_waiter.py Show resolved Hide resolved

tests/_internal/test_waiter.py Show resolved Hide resolved

src/libtmux/_internal/waiter.py Show resolved Hide resolved

tests/_internal/test_waiter.py Show resolved Hide resolved

tests/_internal/test_waiter.py Show resolved Hide resolved

tony force-pushed the waiter-2.0 branch 6 times, most recently from 43eca42 to 962d643 Compare February 27, 2025 16:55

tony force-pushed the waiter-2.0 branch 4 times, most recently from 07e3af1 to 67350d4 Compare February 27, 2025 18:15

sourcery-ai bot reviewed Feb 27, 2025

View reviewed changes

tests/_internal/test_waiter.py Show resolved Hide resolved

src/libtmux/_internal/waiter.py Show resolved Hide resolved

tests/_internal/test_waiter.py Show resolved Hide resolved

tony force-pushed the waiter-2.0 branch 2 times, most recently from e8c23de to c0de412 Compare February 27, 2025 18:23

tony added 11 commits February 27, 2025 12:38

chore: Add __init__.py for tests/examples

1668b45

chore: Add __init__.py for tests/examples/test

fc3dec2

chore: Add __init__.py for tests/examples/_internal/waiter

a438f2d

fix(retry): Improve retry_until_extended function with better error m…

aa260f2

…essaging - Add descriptive timeout message to WaitTimeout exception - Ensure consistent handling of timeout errors - Fix type hints for function return values

pyproject(mypy[exceptions]): examples to ignore no-untyped-def

6bdbb5c

test: add conftest.py to register example marker

d436d75

- Adds a conftest.py file in tests/examples to register the pytest.mark.example marker - Eliminates pytest warnings about unknown markers in example tests - Improves test output by removing noise from warnings

docs(CHANGES) Note Waiter

50081b5

tony force-pushed the waiter-2.0 branch from c0de412 to 50081b5 Compare February 27, 2025 18:39

sourcery-ai bot reviewed Feb 27, 2025

View reviewed changes

tests/examples/_internal/waiter/test_fluent_chaining.py Show resolved Hide resolved

src/libtmux/_internal/waiter.py Show resolved Hide resolved

tests/_internal/test_waiter.py Show resolved Hide resolved

tony merged commit db47652 into master Feb 27, 2025
26 checks passed

tony deleted the waiter-2.0 branch February 27, 2025 18:42

This was referenced Feb 27, 2025

Use waiter 2.0 #583

Closed

Perfect mocking mechanism #591

Open

tony changed the title ~~Waiter 2.0~~ Waiter 0.1 Apr 6, 2025

tony mentioned this pull request Apr 6, 2025

Waiter 0.1 #594

Open

tony changed the title ~~Waiter 0.1~~ [Reverted] Waiter 0.1 Apr 6, 2025

Conversation

tony commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sourcery-ai bot commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide by Sourcery

Sequence diagram for wait_for_pane_content with regex

Sequence diagram for fluent API usage

Updated class diagram for PaneContentWaiter

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

codecov bot commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

tony commented Feb 26, 2025

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tony commented Feb 27, 2025

Uh oh!

tony commented Feb 27, 2025

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tony commented Feb 27, 2025

Uh oh!

tony commented Feb 27, 2025

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tony commented Feb 27, 2025

Uh oh!

tony commented Feb 27, 2025

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tony commented Feb 26, 2025 •

edited

Loading

sourcery-ai bot commented Feb 26, 2025 •

edited

Loading

codecov bot commented Feb 26, 2025 •

edited

Loading