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.
