Add wait_for_event API and clean connection docs

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

Author: cursoragent

.github/copilot-instructions.md~

@@ -57,9 +57,12 @@ async def main():
     # Connect to a Chrome DevTools Protocol endpoint
     async with CDPConnection("ws://localhost:9222/devtools/page/YOUR_PAGE_ID") as conn:
         # Navigate to a URL
-        frame_id, loader_id, error = await conn.execute(
+        frame_id, loader_id, error_text, is_download = await conn.execute(
             page.navigate(url="https://example.com")
         )
+
+        # Wait for a specific event type
+        await conn.wait_for_event(page.LoadEventFired, timeout=5.0)
         print(f"Navigated to example.com, frame_id: {frame_id}")
 
 asyncio.run(main())
@@ -70,7 +73,7 @@ asyncio.run(main())
 - **WebSocket Management**: Automatic connection lifecycle management with async context managers
 - **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 Handling**: Async iterators plus typed waiting via `wait_for_event(...)`
 - **Error Handling**: Comprehensive error handling with typed exceptions
 
 See the [examples directory](examples/) for more usage patterns.
@@ -88,39 +91,6 @@ assert repr(frame_id) == "FrameId('my id')"
 
 ## API Documentation
 
-For detailed API documentation, see:
-
-- **[Complete Documentation](https://py-cdp.readthedocs.io)** - Full API reference on Read the Docs
-- **[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)** - Official CDP specification
-- **[Examples](examples/)** - Code examples demonstrating usage patterns
-
-### Key Modules
-
-- `cdp.connection` - WebSocket I/O and connection management (I/O mode)
-- `cdp.<domain>` - Type wrappers for each CDP domain (e.g., `cdp.page`, `cdp.network`, `cdp.runtime`)
-- Each domain module provides types, commands, and events for that CDP domain
-
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
-
-- Setting up your development environment
-- Running tests and type checking
-- Submitting pull requests
-- Reporting issues
-
-Please also read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
-
-## Security
-
-For information about reporting security vulnerabilities, please see our [Security Policy](SECURITY.md).
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## API Reference
-
 The library provides Python wrappers for all Chrome DevTools Protocol domains:
 
 - **Page**: Page control (navigation, screenshots, etc.)
@@ -132,7 +102,18 @@ The library provides Python wrappers for all Chrome DevTools Protocol domains:
 - **Security**: Security-related information
 - And many more...
 
-For complete API documentation, visit [py-cdp.readthedocs.io](https://py-cdp.readthedocs.io).
+For detailed API documentation, see:
+
+- **[Complete Documentation](https://py-cdp.readthedocs.io)** - Full API reference on Read the Docs
+- **[Connection Guide](docs/connection.md)** - I/O mode, multiplexing, and event waiting helpers
+- **[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)** - Official CDP specification
+- **[Examples](examples/)** - Usage patterns and runnable snippets
+
+### Key Modules
+
+- `cdp.connection` - WebSocket I/O and connection management (I/O mode)
+- `cdp.<domain>` - Type wrappers for each CDP domain (e.g., `cdp.page`, `cdp.network`, `cdp.runtime`)
+- Each domain module provides types, commands, and events for that CDP domain
 
 ### Type System
 
@@ -144,13 +125,18 @@ All CDP types, commands, and events are fully typed with Python type hints, prov
 
 ## 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
+We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- development setup
+- test and type-check commands
+- pull request workflow
+- bug and feature reporting
+
+Please also read our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
 
-For questions or discussions, feel free to open an issue on GitHub.
+For vulnerability reporting, see [SECURITY.md](SECURITY.md).
 
 ## License
 

README.md

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 import asyncio
+from collections import deque
 import json
 import logging
 import typing
@@ -25,6 +26,7 @@
 
 
 logger = logging.getLogger(__name__)
+T_Event = typing.TypeVar('T_Event')
 
 
 class CDPError(Exception):
@@ -96,6 +98,7 @@ def __init__(self, url: str, timeout: float = 30.0):
         self._next_command_id = 1
         self._pending_commands: typing.Dict[int, PendingCommand] = {}
         self._event_queue: asyncio.Queue = asyncio.Queue()
+        self._event_buffer: typing.Deque[typing.Any] = deque()
         self._recv_task: typing.Optional[asyncio.Task] = None
         self._closed = False
 
@@ -131,6 +134,7 @@ async def close(self) -> None:
             if not pending.future.done():
                 pending.future.cancel()
         self._pending_commands.clear()
+        self._event_buffer.clear()
 
         # Close the WebSocket
         if self._ws:
@@ -311,13 +315,91 @@ async def listen(self) -> typing.AsyncIterator[typing.Any]:
         """
         while not self._closed:
             try:
+                if self._event_buffer:
+                    yield self._event_buffer.popleft()
+                    continue
                 event = await asyncio.wait_for(self._event_queue.get(), timeout=1.0)
                 yield event
             except asyncio.TimeoutError:
                 # Check if connection is still alive
                 if self._closed:
                     break
                 continue
+
+    async def wait_for_event(
+        self,
+        event_type: typing.Union[typing.Type[T_Event], typing.Tuple[typing.Type[T_Event], ...]],
+        predicate: typing.Optional[typing.Callable[[T_Event], bool]] = None,
+        timeout: typing.Optional[float] = None
+    ) -> T_Event:
+        """
+        Wait for the next event that matches the given type and optional predicate.
+
+        Any non-matching events are retained internally and remain available via
+        ``listen()`` or ``get_event_nowait()``.
+
+        Args:
+            event_type: Expected event class (or tuple of classes).
+            predicate: Optional additional filter for matching events.
+            timeout: Optional timeout in seconds.
+
+        Returns:
+            The first matching event.
+
+        Raises:
+            asyncio.TimeoutError: If no matching event is received in time.
+            CDPConnectionError: If the connection is closed while waiting.
+        """
+        if timeout is not None and timeout < 0:
+            raise ValueError('timeout must be >= 0')
+
+        # First inspect buffered events before waiting for new ones.
+        buffered: typing.Deque[typing.Any] = deque()
+        while self._event_buffer:
+            event = self._event_buffer.popleft()
+            if isinstance(event, event_type) and (predicate is None or predicate(event)):
+                self._event_buffer.extendleft(reversed(buffered))
+                return event
+            buffered.append(event)
+        self._event_buffer.extendleft(reversed(buffered))
+
+        loop = asyncio.get_running_loop()
+        deadline = None if timeout is None else (loop.time() + timeout)
+
+        while True:
+            if self._closed:
+                raise CDPConnectionError('Connection closed while waiting for event')
+
+            remaining: typing.Optional[float] = None
+            if deadline is not None:
+                remaining = deadline - loop.time()
+                if remaining <= 0:
+                    break
+
+            try:
+                event = await asyncio.wait_for(self._event_queue.get(), timeout=remaining)
+            except asyncio.TimeoutError as exc:
+                raise asyncio.TimeoutError(
+                    f'No event of type {self._event_type_name(event_type)} before timeout'
+                ) from exc
+
+            if isinstance(event, event_type) and (predicate is None or predicate(event)):
+                return event
+
+            self._event_buffer.append(event)
+
+        raise asyncio.TimeoutError(
+            f'No event of type {self._event_type_name(event_type)} before timeout'
+        )
+
+    @staticmethod
+    def _event_type_name(
+        event_type: typing.Union[typing.Type[typing.Any], typing.Tuple[typing.Type[typing.Any], ...]]
+    ) -> str:
+        """Return a display name for event type annotations."""
+        if isinstance(event_type, tuple):
+            return ', '.join(t.__name__ for t in event_type)
+        return event_type.__name__
 
     def get_event_nowait(self) -> typing.Optional[typing.Any]:
         """
@@ -326,6 +408,8 @@ def get_event_nowait(self) -> typing.Optional[typing.Any]:
         Returns:
             A CDP event object, or None if no events are available
         """
+        if self._event_buffer:
+            return self._event_buffer.popleft()
         try:
             return self._event_queue.get_nowait()
         except asyncio.QueueEmpty:

cdp/connection.py

@@ -21,7 +21,7 @@ async def main():
     # Connect using async context manager
     async with CDPConnection("ws://localhost:9222/devtools/page/YOUR_PAGE_ID") as conn:
         # Execute a command
-        frame_id, loader_id, error = await conn.execute(
+        frame_id, loader_id, error_text, is_download = await conn.execute(
             page.navigate(url="https://example.com")
         )
 
@@ -120,6 +120,19 @@ if event:
     print(f"Got event: {event}")
 ```
 
+Wait for a specific event type (with optional filtering):
+
+```python
+load_event = await conn.wait_for_event(page.LoadEventFired, timeout=5.0)
+print(f"Loaded at timestamp: {load_event.timestamp}")
+
+# Wait for a matching event
+late_event = await conn.wait_for_event(
+    page.LoadEventFired,
+    predicate=lambda evt: evt.timestamp > load_event.timestamp
+)
+```
+
 ### Error Handling
 
 The connection module provides typed exceptions:
@@ -160,6 +173,7 @@ class CDPConnection:
     async def connect(self) -> None
     async def close(self) -> None
     async def execute(self, cmd, timeout: Optional[float] = None) -> Any
+    async def wait_for_event(self, event_type, predicate=None, timeout=None) -> Any
     async def listen(self) -> AsyncIterator[Any]
     def get_event_nowait(self) -> Optional[Any]
 

docs/connection.md

@@ -54,26 +54,17 @@ async def event_handling_example():
     async with CDPConnection(url) as conn:
         # Enable page domain to receive events
         await conn.execute(page.enable())
-        
-        # Start navigation
+
+        # Start navigation and wait for a specific event.
         print("Starting navigation...")
-        nav_task = asyncio.create_task(
-            conn.execute(page.navigate(url="https://example.com"))
-        )
-        
-        # Listen for events while navigation is in progress
-        event_count = 0
-        async for event in conn.listen():
-            print(f"Received event: {type(event).__name__}")
-            event_count += 1
-            
-            # Stop after receiving a few events
-            if event_count >= 3:
-                break
-        
-        # Wait for navigation to complete
-        await nav_task
-        print("Navigation complete!")
+        await conn.execute(page.navigate(url="https://example.com"))
+        load_event = await conn.wait_for_event(page.LoadEventFired, timeout=5.0)
+        print(f"Page loaded at timestamp: {load_event.timestamp}")
+
+        # You can still iterate over queued events.
+        event = conn.get_event_nowait()
+        if event:
+            print(f"Next queued event: {type(event).__name__}")
 
 
 async def multiplexing_example():