Metadata-Version: 2.4
Name: playwrong
Version: 0.1.0
Summary: Lightweight CDP-first browser automation; users are responsible for lawful authorized use.
Author: playwrong contributors
License: MIT
Project-URL: Homepage, https://github.com/your-org/playwrong
Project-URL: Repository, https://github.com/your-org/playwrong
Project-URL: Issues, https://github.com/your-org/playwrong/issues
Project-URL: Security, https://github.com/your-org/playwrong/security/policy
Keywords: cdp,browser-automation,chromium,edge,selenium,playwright-like
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: selenium>=4.20.0
Requires-Dist: websocket-client>=1.8.0
Dynamic: license-file

# playwrong

`playwrong` is a lightweight browser automation library with a Playwright-like sync/async surface.

If you are an AI coding assistant working on this package, read `ai_agent.md` first.

It is focused on practical scraping workflows:

- wrap headful crawling around an already-existing browser instance when available
- attach to an already-open Chromium/Edge CDP endpoint when possible
- launch a new debug browser if no endpoint is available
- provide a small, familiar API (`sync_playwright`, `chromium.launch`, `connect_over_cdp`, `new_page`, `goto`, `content`)
- optional Firefox backend via Selenium + local `undetected_geckodriver` wrapper

Primary intent: allow operators to inject an already-running browser into headful crawling so automation can reuse an established session (cookies/auth state) instead of starting from a cold profile every run.

This way you can still get served relevant ads while automating your browser hehe.

## Status

Early alpha (`0.x`). API may evolve.

## Install

```bash
python -m pip install -e .
```

## Publishing to PyPI

This package includes GitHub Actions pipelines for build/test and publish:

- `projects/playwrong/.github/workflows/ci.yml`
- `projects/playwrong/.github/workflows/publish-pypi.yml`

Publish flow is configured for trusted publishing with `pypa/gh-action-pypi-publish`.

Recommended release process:

1. Push/tag a release (`vX.Y.Z`) and publish a GitHub Release.
2. Ensure repository environment `pypi` exists and is approved for publishing.
3. Configure PyPI trusted publisher for your GitHub repository/workflow.

## Quick start

```python
from playwrong.sync_api import sync_playwright

with sync_playwright(verbose=True) as p:
    browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
    page = browser.new_page()
    page.goto("https://example.com", wait_until="load")
    html = page.content()
    browser.close()
```

## Open-browser attach

Start Edge/Chrome with remote debugging first, for example:

```powershell
& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\edge-cdp-profile" about:blank
```

Then connect:

```python
browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
```

## API surface

- `sync_playwright(...)`
- `async_playwright(...)`
- `p.chromium.launch(...)`
- `p.chromium.connect_over_cdp(endpoint)`
- `p.firefox.launch(...)`
- `browser.new_context(...)`
- `browser.new_page()`
- `page.goto(url, wait_until="load", timeout=...)`
- `page.content()`
- `browser.close()`

## Environment variables

- `PLAYWRONG_PREFER_OPEN` (`true`/`false`)
- `PLAYWRONG_CDP_ENDPOINTS` (comma-separated URLs)
- `PLAYWRONG_CDP_TIMEOUT_SECONDS` (float)
- `PLAYWRONG_VERBOSE` (`true`/`false`)

## Notes

- Edge-compatible target creation uses `PUT /json/new?url=...` because modern Edge returns `405` on `GET /json/new`.
- Firefox attach-to-existing-session is not supported; Firefox launches a new WebDriver session.
- This package intentionally exposes a minimal subset rather than full Playwright parity.

## Legal Responsibility

This library is distributed as a general-purpose automation toolkit.

- The maintainers/publishers of `playwrong` do not grant permission to access any specific website, service, or data source.
- Compliance with laws, contracts, robots policies, terms of service, and internal security/privacy requirements is solely the responsibility of the user/operator.
- Users are responsible for obtaining any required authorization before automating browser actions.
- The software is provided under the project license on an "AS IS" basis, without legal or compliance warranties.

See `SECURITY.md` for reporting and security policy details.
