pypecdp 0.3.0__tar.gz

pypecdp-0.3.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,70 @@
+name: Publish distribution 📦 to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Verify package can be imported
+      run: |
+        python3 -m pip install dist/*.whl
+        python3 -c "import pypecdp; print(f'✓ Package version: {pypecdp.__version__}')"
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+  publish-to-pypi:
+    name: >-
+      Publish distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pypecdp
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v6
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Validate version matches tag
+      run: |
+        # Extract version from package filename
+        WHEEL_FILE=$(ls dist/*.whl)
+        PKG_VERSION=$(echo $WHEEL_FILE | sed -n 's/.*pypecdp-\([0-9.]*\)-.*/\1/p')
+        # Extract version from tag (remove 'v' prefix if present)
+        TAG_VERSION=${GITHUB_REF#refs/tags/}
+        TAG_VERSION=${TAG_VERSION#v}
+        echo "Package version: $PKG_VERSION"
+        echo "Tag version: $TAG_VERSION"
+        if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+          echo "❌ Error: Package version ($PKG_VERSION) does not match tag ($TAG_VERSION)"
+          exit 1
+        fi
+        echo "✓ Version validation passed"
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

pypecdp-0.3.0/.gitignore

@@ -0,0 +1,56 @@
+# Temporary and binary files
+*~
+*.py[cod]
+*.so
+*.cfg
+!.isort.cfg
+!setup.cfg
+*.orig
+*.log
+*.pot
+__pycache__/*
+.cache/*
+.*.swp
+*/.ipynb_checkpoints/*
+.DS_Store
+src/*.py
+
+# Project files
+.ropeproject
+.project
+.pydevproject
+.settings
+.idea
+.vscode
+tags
+
+# Package files
+*.egg
+*.eggs/
+.installed.cfg
+*.egg-info
+
+# Unittest and coverage
+htmlcov/*
+.coverage
+.coverage.*
+.tox
+junit*.xml
+coverage.xml
+.pytest_cache/
+
+# Build and docs folder/files
+build/*
+dist/*
+sdist/*
+docs/api/*
+docs/_rst/*
+docs/_build/*
+cover/*
+MANIFEST
+
+# Per-project virtualenvs
+.venv*/
+.conda*/
+.python-version
+/.mypy_cache/

pypecdp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 sohaib17
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pypecdp-0.3.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include src/pypecdp *.py

pypecdp-0.3.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: pypecdp
+Version: 0.3.0
+Summary: Async Chrome DevTools Protocol over POSIX pipes.
+Project-URL: Homepage, https://github.com/sohaib17/pypecdp
+Project-URL: Source, https://github.com/sohaib17/pypecdp
+Project-URL: Issues, https://github.com/sohaib17/pypecdp/issues
+Author: sohaib17
+License: MIT License
+License-File: LICENSE
+Keywords: asyncio,automation,cdp,chrome,chromium,devtools,headless
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: deprecated>=1.2.0
+Description-Content-Type: text/markdown
+
+# pypecdp
+
+Fully async Chrome DevTools Protocol over POSIX pipes with a high-level Browser/Tab/Elem API for Python 3.12+ on Linux.
+
+Chrome automation using `--remote-debugging-pipe` (no websockets, no ports, just pipes) with bundled CDP protocol classes.
+
+Inspired by [playwright-python](https://github.com/microsoft/playwright-python), [python-cdp](https://github.com/HMaker/python-cdp) and [nodriver](https://github.com/ultrafunkamsterdam/nodriver).
+
+## Features
+
+- **Fully Async**: Built from ground up with asyncio for concurrent operations
+- **Fast**: Direct pipe communication via file descriptors - no websockets, no network overhead
+- **Zero dependencies**: No external dependencies required - built-in Python libraries only
+- **Secure**: Browser only communicates over local pipes, no open ports accessible to other processes
+- **No zombies**: No risk of orphaned Chrome processes - automatic lifecycle management
+- **Linux focused**: Leverages POSIX pipes and process management
+
+## Install
+
+```bash
+pip install pypecdp
+```
+
+Install Chromium if needed:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install chromium-browser
+
+# Fedora
+sudo dnf install chromium
+
+# Arch
+sudo pacman -S chromium
+```
+
+## Quick Start
+
+```python
+import asyncio
+from pypecdp import Browser
+
+async def main():
+    # Launch browser
+    browser = await Browser.start(
+        chrome_path="chromium",
+        headless=True
+    )
+    
+    # Open a tab
+    tab = await browser.navigate("https://example.com")
+    
+    # Select and interact with elements
+    h1 = await tab.select("h1")
+    if h1:
+        text = await h1.text()
+        print(f"Page heading: {text}")
+    
+    # Evaluate JavaScript
+    result = await tab.eval("document.title")
+    print(f"Title: {result.value}")
+    
+    # Close browser
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Usage Guide
+
+### Browser Management
+
+```python
+from pypecdp import Browser, Config
+
+# Simple start
+browser = await Browser.start(chrome_path="chromium", headless=True)
+
+# Advanced configuration
+config = Config(
+    chrome_path="/usr/bin/google-chrome",
+    user_data_dir="/tmp/chrome-profile",
+    headless=True,
+    extra_args=["--no-sandbox", "--disable-gpu"],
+    switches={"disable-blink-features": "AutomationControlled"},
+    env={"LANG": "en_US.UTF-8"}
+)
+browser = await Browser.start(config=config)
+
+# Close browser
+await browser.close()
+```
+
+### Event Handlers
+
+```python
+from pypecdp import cdp
+
+# Tab-level events (requires domain enable!)
+await tab.send(cdp.runtime.enable())  # Required for runtime events!
+
+async def on_console(event):
+    print(f"Console {event.type_}: {event.args}")
+
+tab.on(cdp.runtime.ConsoleAPICalled, on_console)
+
+# Browser-level events
+async def on_target_created(event):
+    info = event.target_info
+    print(f"Target created: {info.type_} - {info.url}")
+
+browser.on(cdp.target.TargetCreated, on_target_created)
+```
+
+### Logging
+
+pypecdp uses Python's standard logging module. Configure via environment variables:
+
+```bash
+# Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+export PYPECDP_LOG_LEVEL=DEBUG
+
+# Set custom logger name
+export PYPECDP_LOGGER=myapp.browser
+```
+
+Or configure the logger directly in Python:
+
+```python
+from pypecdp import logger
+import logging
+
+# Set log level
+logger.setLevel(logging.DEBUG)
+
+# Add custom handler
+handler = logging.FileHandler("pypecdp.log")
+logger.addHandler(handler)
+```
+
+## Error Handling
+
+```python
+try:
+    browser = await Browser.start()
+    tab = await browser.navigate("https://example.com")
+    
+    # Your automation code
+    result = await tab.eval("document.title")
+    
+except RuntimeError as e:
+    # CDP protocol errors
+    print(f"CDP Error: {e}")
+except ConnectionError as e:
+    # Connection lost
+    print(f"Connection Error: {e}")
+except Exception as e:
+    # Other errors
+    print(f"Error: {e}")
+finally:
+    # Always cleanup
+    await browser.close()
+```
+
+## Requirements
+
+- Python 3.12+
+- Linux (uses POSIX pipes and `preexec_fn`)
+- Chromium or Google Chrome
+
+## Links
+
+- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Contributing
+
+Contributions welcome! This project aims to provide a clean, type-safe interface to Chrome automation on Linux.

pypecdp-0.3.0/README.md

@@ -0,0 +1,181 @@
+# pypecdp
+
+Fully async Chrome DevTools Protocol over POSIX pipes with a high-level Browser/Tab/Elem API for Python 3.12+ on Linux.
+
+Chrome automation using `--remote-debugging-pipe` (no websockets, no ports, just pipes) with bundled CDP protocol classes.
+
+Inspired by [playwright-python](https://github.com/microsoft/playwright-python), [python-cdp](https://github.com/HMaker/python-cdp) and [nodriver](https://github.com/ultrafunkamsterdam/nodriver).
+
+## Features
+
+- **Fully Async**: Built from ground up with asyncio for concurrent operations
+- **Fast**: Direct pipe communication via file descriptors - no websockets, no network overhead
+- **Zero dependencies**: No external dependencies required - built-in Python libraries only
+- **Secure**: Browser only communicates over local pipes, no open ports accessible to other processes
+- **No zombies**: No risk of orphaned Chrome processes - automatic lifecycle management
+- **Linux focused**: Leverages POSIX pipes and process management
+
+## Install
+
+```bash
+pip install pypecdp
+```
+
+Install Chromium if needed:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install chromium-browser
+
+# Fedora
+sudo dnf install chromium
+
+# Arch
+sudo pacman -S chromium
+```
+
+## Quick Start
+
+```python
+import asyncio
+from pypecdp import Browser
+
+async def main():
+    # Launch browser
+    browser = await Browser.start(
+        chrome_path="chromium",
+        headless=True
+    )
+    
+    # Open a tab
+    tab = await browser.navigate("https://example.com")
+    
+    # Select and interact with elements
+    h1 = await tab.select("h1")
+    if h1:
+        text = await h1.text()
+        print(f"Page heading: {text}")
+    
+    # Evaluate JavaScript
+    result = await tab.eval("document.title")
+    print(f"Title: {result.value}")
+    
+    # Close browser
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Usage Guide
+
+### Browser Management
+
+```python
+from pypecdp import Browser, Config
+
+# Simple start
+browser = await Browser.start(chrome_path="chromium", headless=True)
+
+# Advanced configuration
+config = Config(
+    chrome_path="/usr/bin/google-chrome",
+    user_data_dir="/tmp/chrome-profile",
+    headless=True,
+    extra_args=["--no-sandbox", "--disable-gpu"],
+    switches={"disable-blink-features": "AutomationControlled"},
+    env={"LANG": "en_US.UTF-8"}
+)
+browser = await Browser.start(config=config)
+
+# Close browser
+await browser.close()
+```
+
+### Event Handlers
+
+```python
+from pypecdp import cdp
+
+# Tab-level events (requires domain enable!)
+await tab.send(cdp.runtime.enable())  # Required for runtime events!
+
+async def on_console(event):
+    print(f"Console {event.type_}: {event.args}")
+
+tab.on(cdp.runtime.ConsoleAPICalled, on_console)
+
+# Browser-level events
+async def on_target_created(event):
+    info = event.target_info
+    print(f"Target created: {info.type_} - {info.url}")
+
+browser.on(cdp.target.TargetCreated, on_target_created)
+```
+
+### Logging
+
+pypecdp uses Python's standard logging module. Configure via environment variables:
+
+```bash
+# Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+export PYPECDP_LOG_LEVEL=DEBUG
+
+# Set custom logger name
+export PYPECDP_LOGGER=myapp.browser
+```
+
+Or configure the logger directly in Python:
+
+```python
+from pypecdp import logger
+import logging
+
+# Set log level
+logger.setLevel(logging.DEBUG)
+
+# Add custom handler
+handler = logging.FileHandler("pypecdp.log")
+logger.addHandler(handler)
+```
+
+## Error Handling
+
+```python
+try:
+    browser = await Browser.start()
+    tab = await browser.navigate("https://example.com")
+    
+    # Your automation code
+    result = await tab.eval("document.title")
+    
+except RuntimeError as e:
+    # CDP protocol errors
+    print(f"CDP Error: {e}")
+except ConnectionError as e:
+    # Connection lost
+    print(f"Connection Error: {e}")
+except Exception as e:
+    # Other errors
+    print(f"Error: {e}")
+finally:
+    # Always cleanup
+    await browser.close()
+```
+
+## Requirements
+
+- Python 3.12+
+- Linux (uses POSIX pipes and `preexec_fn`)
+- Chromium or Google Chrome
+
+## Links
+
+- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Contributing
+
+Contributions welcome! This project aims to provide a clean, type-safe interface to Chrome automation on Linux.

pypecdp-0.3.0/example/console_logger.py

@@ -0,0 +1,165 @@
+"""Example: Console logging using Runtime.consoleAPICalled events.
+
+Demonstrates how to capture and monitor console messages from the browser:
+- Subscribing to Runtime.consoleAPICalled events
+- Capturing console.log, console.warn, console.error messages
+- Extracting and displaying console message arguments
+- Real-time console monitoring during page execution
+"""
+
+import asyncio
+import base64
+import os
+from typing import Any
+
+from pypecdp import Browser, cdp
+
+
+async def main() -> None:
+    """Main."""
+    # Launch browser
+    browser = await Browser.start(
+        chrome_path=os.environ.get("PYPECDP_CHROME_PATH", "chromium"),
+        headless=True,
+        extra_args=["--no-sandbox"],
+    )
+
+    tab = await browser.navigate("about:blank")
+    await tab.send(cdp.runtime.enable())
+    print("Browser launched\n")
+
+    # Storage for console messages
+    console_messages: list[tuple[str, str]] = []
+
+    # Handler for console API calls
+    async def handle_console(event: Any) -> None:
+        """Handle Runtime.consoleAPICalled events."""
+        # event is a ConsoleAPICalled object
+        msg_type = event.type_
+        args = event.args
+
+        # Extract values from arguments
+        values = []
+        for arg in args:
+            arg_type = arg.type_
+            if arg_type == "string":
+                values.append(arg.value if hasattr(arg, "value") else "")
+            elif arg_type == "number":
+                values.append(str(arg.value if hasattr(arg, "value") else ""))
+            elif arg_type == "boolean":
+                values.append(str(arg.value if hasattr(arg, "value") else ""))
+            elif arg_type == "object":
+                desc = (
+                    arg.description
+                    if hasattr(arg, "description")
+                    else "Object"
+                )
+                values.append(desc)
+            else:
+                values.append(f"[{arg_type}]")
+
+        message = " ".join(values)
+
+        # Format with prefix markers
+        prefix = {
+            "log": "[i]",
+            "info": "[i]",
+            "warn": "[!]",
+            "error": "[x]",
+            "debug": "[d]",
+        }.get(msg_type, "[*]")
+
+        formatted = f"{prefix} [{msg_type.upper()}] {message}"
+        console_messages.append((msg_type, message))
+        print(formatted)
+
+    # Register the console handler
+    tab.on(cdp.runtime.ConsoleAPICalled, handle_console)
+
+    print("=" * 60)
+    print("Capturing console messages...")
+    print("=" * 60 + "\n")
+
+    # Execute various console commands
+    await tab.eval("console.log('Hello from pypecdp!')")
+    await asyncio.sleep(0.1)
+
+    await tab.eval("console.log('Multiple', 'arguments', 123)")
+    await asyncio.sleep(0.1)
+
+    await tab.eval("console.warn('This is a warning')")
+    await asyncio.sleep(0.1)
+
+    await tab.eval("console.error('This is an error')")
+    await asyncio.sleep(0.1)
+
+    await tab.eval("console.info('Info message with number:', 42)")
+    await asyncio.sleep(0.1)
+
+    await tab.eval("console.log('Boolean:', true, false)")
+    await asyncio.sleep(0.1)
+
+    await tab.eval("console.log('Object:', {foo: 'bar', num: 123})")
+    await asyncio.sleep(0.1)
+
+    await tab.eval("console.log('Array:', [1, 2, 3])")
+    await asyncio.sleep(0.1)
+
+    # Navigate to a page and capture its console output
+    print("\n" + "=" * 60)
+    print("Navigating to page with console output...")
+    print("=" * 60 + "\n")
+
+    # Create a page with console output
+    html_content = """
+    <!DOCTYPE html>
+    <html>
+    <head><title>Console Test</title></head>
+    <body>
+        <h1>Console Test Page</h1>
+        <script>
+            console.log('Page loaded!');
+            console.info('Current URL:', window.location.href);
+            console.warn('This is a warning from the page');
+            
+            setTimeout(() => {
+                console.log('Delayed message after 500ms');
+            }, 500);
+            
+            setTimeout(() => {
+                console.error('Simulated error after 1000ms');
+            }, 1000);
+        </script>
+    </body>
+    </html>
+    """
+
+    # Navigate to data URL with the HTML
+    encoded = base64.b64encode(html_content.encode()).decode()
+    await tab.navigate(f"data:text/html;base64,{encoded}")
+
+    # Wait for delayed messages
+    await asyncio.sleep(1.5)
+
+    # Summary
+    print("\n" + "=" * 60)
+    print("Summary")
+    print("=" * 60)
+    print(f"Total console messages captured: {len(console_messages)}")
+
+    # Count by type
+    type_counts: dict[str, int] = {}
+    for msg_type, _ in console_messages:
+        type_counts[msg_type] = type_counts.get(msg_type, 0) + 1
+
+    print("\nBreakdown by type:")
+    for msg_type, count in sorted(type_counts.items()):
+        print(f"  {msg_type}: {count}")
+
+    # Clean up
+    await browser.close()
+    print("\nBrowser closed")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())