`Pane.capture_pane` helpers

[tony]

Changes

feat: Add test_snapshot

Test plan

Coverage

uv run pytest --cov=libtmux.snapshot tests/test_snapshot.py -v

Automatic

Summary by Sourcery

Introduce snapshot and recording functionality for tmux panes. This allows capturing and analyzing pane content and metadata at various points in time. Add tests to verify the correctness of the new features.

New Features:

• Introduce Pane.snapshot() to create a snapshot of the pane's current state.
• Introduce Pane.record() to create a recording of pane snapshots.
• Add PaneSnapshot class to store pane content and metadata.
• Add PaneRecording class to manage a time-series of pane snapshots.
• Add test_snapshot to test the snapshot functionality and ensure correctness of capturing pane content and metadata.
• Add test_pane_recording to test the recording functionality, including adding snapshots, iterating through them, and filtering by time.

Tests:

• Add tests for snapshot and recording functionality.

[sourcery-ai[bot]]

Reviewer's Guide by Sourcery

This pull request introduces snapshot and recording functionality for tmux panes. It adds PaneSnapshot and PaneRecording classes, along with corresponding methods in the Pane class, to facilitate capturing and managing pane states for testing and debugging.

Sequence diagram for creating a PaneSnapshot

sequenceDiagram
    participant User
    participant Pane
    participant PaneSnapshot

    User->>Pane: snapshot(start, end)
    Pane->>PaneSnapshot: from_pane(self, start, end)
    activate PaneSnapshot
    PaneSnapshot-->>Pane: PaneSnapshot instance
    deactivate PaneSnapshot
    Pane-->>User: PaneSnapshot instance

Sequence diagram for creating a PaneRecording and adding a snapshot

sequenceDiagram
    participant User
    participant Pane
    participant PaneRecording
    participant PaneSnapshot

    User->>Pane: record()
    Pane->>PaneRecording: PaneRecording()
    activate PaneRecording
    PaneRecording-->>Pane: PaneRecording instance
    deactivate PaneRecording
    User->>PaneRecording: add_snapshot(pane, start, end)
    PaneRecording->>Pane: snapshot(start, end)
    Pane->>PaneSnapshot: from_pane(self, start, end)
    activate PaneSnapshot
    PaneSnapshot-->>Pane: PaneSnapshot instance
    deactivate PaneSnapshot
    Pane->>PaneRecording: append(PaneSnapshot)
    PaneRecording-->>User: void

Updated class diagram for Pane, PaneSnapshot, and PaneRecording

classDiagram
    class Pane {
        +capture_pane()
        +snapshot()
        +record()
    }
    class PaneSnapshot {
        +content: list[str]
        +timestamp: datetime
        +pane_id: str
        +window_id: str
        +session_id: str
        +server_name: str
        +metadata: dict[str, str]
        +from_pane()
        +content_str
    }
    class PaneRecording {
        +snapshots: list[PaneSnapshot]
        +add_snapshot()
        +latest
        +get_snapshots_between()
    }
    Pane -- PaneSnapshot : creates
    Pane -- PaneRecording : creates
    PaneRecording -- PaneSnapshot : contains

File-Level Changes

Change	Details	Files
Introduces PaneSnapshot and PaneRecording classes for capturing and recording pane states.	Adds PaneSnapshot dataclass to represent a frozen snapshot of a pane's state, including content, timestamp, and metadata. Adds PaneRecording dataclass to maintain a time-series of PaneSnapshot objects. Implements methods for creating snapshots from a pane and adding them to a recording. Implements methods for iterating, indexing, and filtering snapshots within a recording.	src/libtmux/snapshot.py tests/test_snapshot.py
Adds snapshot and record methods to the Pane class.	Adds snapshot method to create a PaneSnapshot from the current pane state. Adds record method to create a new PaneRecording instance for the pane.	src/libtmux/pane.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[bot]]

Codecov Report

Attention: Patch coverage is 99.03846% with 2 lines in your changes missing coverage. Please review.

Project coverage is 89.27%. Comparing base (92660e4) to head (734d41a).

Files with missing lines	Patch %	Lines
src/libtmux/snapshot.py	97.01%	1 Missing and 1 partial :warning:

Additional details and impacted files

@@                 Coverage Diff                  @@
##           context-managers     #568      +/-   ##
====================================================
+ Coverage             88.84%   89.27%   +0.42%     
====================================================
  Files                    36       38       +2     
  Lines                  4080     4288     +208     
  Branches                376      378       +2     
====================================================
+ Hits                   3625     3828     +203     
- Misses                  310      313       +3     
- Partials                145      147       +2     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.