Add CDPConnection.execute_many and clean docs/artifacts

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

Author: cursoragent

.github/copilot-instructions.md~

@@ -26,3 +26,4 @@ htmlcov/
 .eggs/
 *.log
 .DS_Store
+*~

.gitignore

@@ -57,7 +57,7 @@ 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")
         )
         print(f"Navigated to example.com, frame_id: {frame_id}")
@@ -73,6 +73,17 @@ asyncio.run(main())
 - **Event Handling**: Async iterator for receiving browser events
 - **Error Handling**: Comprehensive error handling with typed exceptions
 
+Batch execution helper:
+
+```python
+results = await conn.execute_many([
+    page.navigate(url="https://example.com"),
+    page.navigate(url="https://example.org"),
+])
+```
+
+Use `return_exceptions=True` to collect command failures in the returned list.
+
 See the [examples directory](examples/) for more usage patterns.
 
 ## Sans-I/O Mode (Original)
@@ -142,18 +153,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

@@ -294,6 +294,42 @@ async def execute(
             # Clean up the pending command on error
             self._pending_commands.pop(cmd_id, None)
             raise
+
+    async def execute_many(
+        self,
+        commands: typing.Iterable[typing.Generator[T_JSON_DICT, T_JSON_DICT, typing.Any]],
+        timeout: typing.Optional[float] = None,
+        return_exceptions: bool = False,
+    ) -> typing.List[typing.Any]:
+        """
+        Execute multiple CDP commands concurrently.
+
+        Args:
+            commands: Iterable of CDP command generators.
+            timeout: Optional timeout override applied to each command.
+            return_exceptions: If True, exceptions are returned in the output
+                list in command order. If False, the first command exception is
+                raised after all commands complete.
+
+        Returns:
+            A list of command results in the same order as ``commands``.
+        """
+        tasks = [
+            asyncio.create_task(self.execute(command, timeout=timeout))
+            for command in commands
+        ]
+
+        if not tasks:
+            return []
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        if return_exceptions:
+            return results
+
+        for result in results:
+            if isinstance(result, BaseException):
+                raise result
+        return results
 
     async def listen(self) -> typing.AsyncIterator[typing.Any]:
         """

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")
         )
 
@@ -95,6 +95,28 @@ async with CDPConnection(url) as conn:
     print(results[2][0].value)  # 6
 ```
 
+For convenience, you can also pass a batch of commands to `execute_many()`:
+
+```python
+async with CDPConnection(url) as conn:
+    results = await conn.execute_many([
+        runtime.evaluate(expression="1 + 1"),
+        runtime.evaluate(expression="2 + 2"),
+        runtime.evaluate(expression="3 + 3"),
+    ])
+    print([result[0].value for result in results])  # [2, 4, 6]
+```
+
+By default, command exceptions are raised. To collect exceptions in-place, set
+`return_exceptions=True`:
+
+```python
+results = await conn.execute_many(commands, return_exceptions=True)
+for item in results:
+    if isinstance(item, Exception):
+        print(f"Command failed: {item}")
+```
+
 ### Event Handling
 
 Listen for browser events using an async iterator:
@@ -160,6 +182,12 @@ class CDPConnection:
     async def connect(self) -> None
     async def close(self) -> None
     async def execute(self, cmd, timeout: Optional[float] = None) -> Any
+    async def execute_many(
+        self,
+        commands,
+        timeout: Optional[float] = None,
+        return_exceptions: bool = False,
+    ) -> List[Any]
     async def listen(self) -> AsyncIterator[Any]
     def get_event_nowait(self) -> Optional[Any]
 

docs/connection.md

@@ -11,6 +11,7 @@ Python wrappers for Chrome DevTools Protocol (CDP).
 
    overview
    getting_started
+   connection
    api
    develop
    changelog

docs/index.rst

@@ -211,6 +211,75 @@ async def test_execute_multiple_commands_multiplexing():
             assert len(mock_ws.sent_messages) == 3
 
 
+@pytest.mark.asyncio
+async def test_execute_many_success():
+    """Test execute_many returns ordered command results."""
+    mock_ws = MockWebSocket()
+
+    # Queue responses in reverse order to verify request multiplexing.
+    mock_ws.queue_message({"id": 2, "result": {"result": {"type": "number", "value": 2}}})
+    mock_ws.queue_message({"id": 1, "result": {"result": {"type": "number", "value": 1}}})
+
+    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:
+            results = await conn.execute_many([
+                runtime.evaluate(expression="1"),
+                runtime.evaluate(expression="2"),
+            ])
+
+            assert len(results) == 2
+            assert isinstance(results[0][0], runtime.RemoteObject)
+            assert isinstance(results[1][0], runtime.RemoteObject)
+            assert results[0][0].value == 1
+            assert results[1][0].value == 2
+            assert len(mock_ws.sent_messages) == 2
+
+
+@pytest.mark.asyncio
+async def test_execute_many_return_exceptions():
+    """Test execute_many can collect exceptions instead of raising."""
+    mock_ws = MockWebSocket()
+
+    # First command succeeds, second command fails.
+    mock_ws.queue_message({"id": 1, "result": {"result": {"type": "number", "value": 1}}})
+    mock_ws.queue_message({"id": 2, "error": {"code": -32602, "message": "Invalid params"}})
+
+    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:
+            results = await conn.execute_many(
+                [
+                    runtime.evaluate(expression="1"),
+                    page.navigate(url="https://example.com"),
+                ],
+                return_exceptions=True,
+            )
+
+            assert len(results) == 2
+            assert isinstance(results[0][0], runtime.RemoteObject)
+            assert results[0][0].value == 1
+            assert isinstance(results[1], CDPCommandError)
+            assert results[1].code == -32602
+
+
+@pytest.mark.asyncio
+async def test_execute_many_raises_first_exception_by_default():
+    """Test execute_many raises command errors by default."""
+    mock_ws = MockWebSocket()
+    mock_ws.queue_message({"id": 1, "error": {"code": -32000, "message": "Command failed"}})
+
+    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(CDPCommandError) as exc_info:
+                await conn.execute_many([page.navigate(url="https://example.com")])
+            assert exc_info.value.code == -32000
+
+
 @pytest.mark.asyncio
 async def test_command_timeout():
     """Test command timeout."""