Add event waiting helper and clean stale files

Co-authored-by: P4x-ng <P4X-ng@users.noreply.github.com>

Author: cursoragent

.github/copilot-instructions.md~

@@ -12,6 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CODE_OF_CONDUCT.md following Contributor Covenant
 - SECURITY.md with security policy
 - This CHANGELOG.md file
+- `CDPConnection.wait_for_event(...)` helper for awaiting typed events with optional predicates
+
+### Changed
+- Expanded I/O mode documentation with event-waiting examples
+- Removed duplicate sections in README to keep docs concise
 
 ## [0.5.0] - 2023
 

CHANGELOG.md

@@ -71,10 +71,23 @@ asyncio.run(main())
 - **JSON-RPC Framing**: Automatic message ID assignment and request/response matching
 - **Command Multiplexing**: Execute multiple commands concurrently with proper tracking
 - **Event Handling**: Async iterator for receiving browser events
+- **Event Waiting Helper**: `wait_for_event(...)` to await specific events with optional filtering
 - **Error Handling**: Comprehensive error handling with typed exceptions
 
 See the [examples directory](examples/) for more usage patterns.
 
+### Waiting for a Specific Event
+
+```python
+from cdp import page
+
+async with CDPConnection(url) as conn:
+    await conn.execute(page.enable())
+    await conn.execute(page.navigate(url="https://example.com"))
+    load_event = await conn.wait_for_event(page.LoadEventFired, timeout=5.0)
+    print(load_event.timestamp)
+```
+
 ## Sans-I/O Mode (Original)
 
 For users who prefer to manage their own I/O:
@@ -142,18 +155,4 @@ All CDP types, commands, and events are fully typed with Python type hints, prov
 - Clear API contracts
 - Inline documentation
 
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
-- How to report bugs and request features
-- Development setup and workflow
-- Coding standards and testing requirements
-- Pull request process
-
-For questions or discussions, feel free to open an issue on GitHub.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
 <a href="https://www.hyperiongray.com/?pk_campaign=github&pk_kwd=pycdp"><img alt="define hyperion gray" width="500px" src="https://hyperiongray.s3.amazonaws.com/define-hg.svg"></a>

README.md

@@ -318,6 +318,77 @@ async def listen(self) -> typing.AsyncIterator[typing.Any]:
                 if self._closed:
                     break
                 continue
+
+    @staticmethod
+    def _format_event_type(
+        event_type: typing.Union[type, typing.Tuple[type, ...]]
+    ) -> str:
+        """Format event type(s) for error messages."""
+        if isinstance(event_type, tuple):
+            return ', '.join(evt.__name__ for evt in event_type)
+        return event_type.__name__
+
+    async def wait_for_event(
+        self,
+        event_type: typing.Union[type, typing.Tuple[type, ...]],
+        timeout: typing.Optional[float] = None,
+        predicate: typing.Optional[typing.Callable[[typing.Any], bool]] = None,
+    ) -> typing.Any:
+        """
+        Wait for the first event matching a type and optional predicate.
+
+        Note:
+            This consumes events from the shared event queue. Events that do not
+            match are discarded.
+
+        Args:
+            event_type: Event class (or tuple of event classes) to match.
+            timeout: Optional timeout in seconds.
+            predicate: Optional callable to further filter matching events.
+
+        Returns:
+            The first matching event instance.
+
+        Raises:
+            CDPConnectionError: If the connection is not open.
+            asyncio.TimeoutError: If timeout elapses before a matching event.
+        """
+        if self._ws is None:
+            raise CDPConnectionError("Not connected")
+
+        if self._closed and self._event_queue.empty():
+            raise CDPConnectionError("Connection closed")
+
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout if timeout is not None else None
+
+        while True:
+            event_type_name = self._format_event_type(event_type)
+
+            try:
+                if deadline is None:
+                    event = await self._event_queue.get()
+                else:
+                    remaining = deadline - loop.time()
+                    if remaining <= 0:
+                        raise asyncio.TimeoutError(
+                            f"Timed out waiting for event {event_type_name}"
+                        )
+                    event = await asyncio.wait_for(self._event_queue.get(), timeout=remaining)
+            except asyncio.TimeoutError:
+                raise asyncio.TimeoutError(
+                    f"Timed out waiting for event {event_type_name}"
+                )
+
+            if isinstance(event, event_type) and (
+                predicate is None or predicate(event)
+            ):
+                return event
+
+            if self._closed and self._event_queue.empty():
+                raise CDPConnectionError(
+                    "Connection closed before matching event was received"
+                )
 
     def get_event_nowait(self) -> typing.Optional[typing.Any]:
         """

cdp/connection.py

@@ -112,6 +112,28 @@ async with CDPConnection(url) as conn:
             print(f"Navigated to {event.frame.url}")
 ```
 
+Wait for a single event directly:
+
+```python
+async with CDPConnection(url) as conn:
+    await conn.execute(page.enable())
+    await conn.execute(page.navigate(url="https://example.com"))
+
+    # Wait for the next load event
+    load_event = await conn.wait_for_event(page.LoadEventFired, timeout=5.0)
+    print(f"Loaded at {load_event.timestamp}")
+```
+
+You can also apply additional filtering logic:
+
+```python
+load_event = await conn.wait_for_event(
+    page.LoadEventFired,
+    timeout=5.0,
+    predicate=lambda evt: evt.timestamp > 0,
+)
+```
+
 You can also get events without blocking:
 
 ```python
@@ -161,6 +183,7 @@ class CDPConnection:
     async def close(self) -> None
     async def execute(self, cmd, timeout: Optional[float] = None) -> Any
     async def listen(self) -> AsyncIterator[Any]
+    async def wait_for_event(self, event_type, timeout: Optional[float] = None, predicate=None) -> Any
     def get_event_nowait(self) -> Optional[Any]
 
     @property

docs/connection.md

@@ -287,6 +287,88 @@ async def test_get_event_nowait():
             assert isinstance(received_event, page.LoadEventFired)
 
 
+@pytest.mark.asyncio
+async def test_wait_for_event():
+    """Test waiting for a specific event type."""
+    mock_ws = MockWebSocket()
+    mock_ws.queue_message({
+        "method": "Page.loadEventFired",
+        "params": {
+            "timestamp": 123456.789
+        }
+    })
+
+    with patch('cdp.connection.websockets.connect', new_callable=AsyncMock) as mock_connect:
+        mock_connect.return_value = mock_ws
+
+        async with CDPConnection("ws://localhost:9222/test") as conn:
+            received_event = await conn.wait_for_event(page.LoadEventFired, timeout=1.0)
+            assert isinstance(received_event, page.LoadEventFired)
+            assert received_event.timestamp == 123456.789
+
+
+@pytest.mark.asyncio
+async def test_wait_for_event_predicate():
+    """Test waiting for an event matching a predicate."""
+    mock_ws = MockWebSocket()
+    mock_ws.queue_message({
+        "method": "Page.loadEventFired",
+        "params": {
+            "timestamp": 1.0
+        }
+    })
+    mock_ws.queue_message({
+        "method": "Page.loadEventFired",
+        "params": {
+            "timestamp": 2.0
+        }
+    })
+
+    with patch('cdp.connection.websockets.connect', new_callable=AsyncMock) as mock_connect:
+        mock_connect.return_value = mock_ws
+
+        async with CDPConnection("ws://localhost:9222/test") as conn:
+            received_event = await conn.wait_for_event(
+                page.LoadEventFired,
+                timeout=1.0,
+                predicate=lambda evt: evt.timestamp > 1.5,
+            )
+            assert isinstance(received_event, page.LoadEventFired)
+            assert received_event.timestamp == 2.0
+
+
+@pytest.mark.asyncio
+async def test_wait_for_event_timeout():
+    """Test waiting for an event times out when none match."""
+    mock_ws = MockWebSocket()
+    # Queue an event that fails the predicate.
+    mock_ws.queue_message({
+        "method": "Page.loadEventFired",
+        "params": {
+            "timestamp": 1.0
+        }
+    })
+
+    with patch('cdp.connection.websockets.connect', new_callable=AsyncMock) as mock_connect:
+        mock_connect.return_value = mock_ws
+
+        async with CDPConnection("ws://localhost:9222/test") as conn:
+            with pytest.raises(asyncio.TimeoutError):
+                await conn.wait_for_event(
+                    page.LoadEventFired,
+                    timeout=0.1,
+                    predicate=lambda evt: evt.timestamp > 2.0,
+                )
+
+
+@pytest.mark.asyncio
+async def test_wait_for_event_not_connected():
+    """Test waiting for an event without a connection."""
+    conn = CDPConnection("ws://localhost:9222/test")
+    with pytest.raises(CDPConnectionError, match="Not connected"):
+        await conn.wait_for_event(page.LoadEventFired)
+
+
 @pytest.mark.asyncio
 async def test_pending_command_count():
     """Test tracking pending command count."""