Metadata-Version: 2.4
Name: pxm2-playwright
Version: 1.0.0
Summary: Official Playwright async/sync proxy rotator and mobile fingerprint helper for PXM2 4G/5G mobile proxies.
Author-email: PXM2 Team <support@pxm2.io>
License-Expression: MIT
Project-URL: Homepage, https://pxm2.io/
Project-URL: Documentation, https://pxm2.io/guides/
Project-URL: Rotating Mobile Proxies, https://pxm2.io/proxy-types/rotating-mobile-proxies/
Project-URL: Bug Tracker, https://pxm2.io/contact/
Keywords: playwright,proxy,mobile-proxy,rotating-proxy,pxm2,web-scraping,automation
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PXM2 Playwright Helper

[![PyPI version](https://img.shields.io/pypi/v/pxm2-playwright.svg)](https://pypi.org/project/pxm2-playwright/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![Playwright](https://img.shields.io/badge/playwright-async%20%7C%20sync-green.svg)](https://playwright.dev/)

Official Playwright automation and proxy rotation client for [PXM2](https://pxm2.io/) dedicated 4G and 5G cellular mobile proxies.

Designed for stealth automation and high-scale web scraping. Integrate [PXM2 Rotating Mobile Proxies](https://pxm2.io/proxy-types/rotating-mobile-proxies/) directly into sync and async Playwright sessions with automatic authentication, mobile carrier Client Hint headers, and instant hardware IP rotation.

Read our step-by-step [Playwright Proxy Automation Guides](https://pxm2.io/guides/) for detailed architectural blueprints.

---

## Features

- **Sync & Async Support**: Native support for both `playwright.sync_api` and `playwright.async_api`.
- **Instant Hardware IP Rotation**: Trigger 1-click cellular modem reconnect webhooks directly from Python with automated reconnection cooldown.
- **Mobile Carrier Device Profiles**: Automatically generate matching mobile headers (`Sec-Ch-Ua`, `Sec-Ch-Ua-Mobile`, `Sec-Ch-Ua-Platform`) and viewport profiles.
- **In-flight IP Verification**: Inspect current external CGNAT IPs through the proxy connection.
- **Zero Heavy Dependencies**: Pure Python standard library implementation.

---

## Installation

```bash
pip install pxm2-playwright
```

---

## Quickstart

### 1. Synchronous Playwright Example

```python
from playwright.sync_api import sync_playwright
from pxm2_playwright import PXM2Playwright

# Initialize PXM2 client
pxm = PXM2Playwright(
    host="proxy.pxm2.io",
    port=10001,
    username="your_username",
    password="your_password",
    rotation_url="https://api.pxm2.io/rotate/YOUR_API_TOKEN",
    cooldown=6.0
)

with sync_playwright() as p:
    browser = p.chromium.launch(
        proxy=pxm.proxy_config(),
        headless=True
    )
    # Apply mobile carrier browser context options
    context = browser.new_context(**pxm.new_context_options(is_mobile=True))
    page = context.new_page()

    page.goto("https://api.ipify.org?format=json")
    print("Initial IP:", page.content())

    # Trigger instant hardware modem IP rotation
    print("Rotating 4G/5G mobile IP...")
    res = pxm.rotate()
    print("Rotation result:", res)

    page.reload()
    print("Rotated IP:", page.content())

    browser.close()
```

---

### 2. Asynchronous Playwright Example

```python
import asyncio
from playwright.async_api import async_playwright
from pxm2_playwright import PXM2Playwright

pxm = PXM2Playwright(
    host="proxy.pxm2.io",
    port=10001,
    username="your_username",
    password="your_password",
    rotation_url="https://api.pxm2.io/rotate/YOUR_API_TOKEN",
    cooldown=6.0
)

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(
            proxy=pxm.proxy_config(),
            headless=True
        )
        context = await browser.new_context(**pxm.new_context_options(is_mobile=True))
        page = await context.new_page()

        await page.goto("https://api.ipify.org?format=json")
        print("Initial IP:", await page.content())

        # Async hardware rotation
        await pxm.async_rotate()

        await page.reload()
        print("New IP:", await page.content())

        await browser.close()

asyncio.run(main())
```

---

## Why PXM2 4G/5G Mobile Proxies?

Websites with advanced bot detection (Cloudflare Turnstile, DataDome, Akamai, PerimeterX) aggressively fingerprint datacenter and commercial residential subnets.

[PXM2](https://pxm2.io/) routes traffic through dedicated cellular modems with SIM cards from tier-1 mobile carriers (AT&T, Verizon, Vodafone, Orange, EE). Mobile IPs are assigned via Carrier-Grade NAT (CGNAT), where thousands of legitimate mobile subscribers share the exact same public IPs, making blanket IP banning virtually impossible.

- [PXM2 Official Website](https://pxm2.io/)
- [Rotating Mobile Proxies](https://pxm2.io/proxy-types/rotating-mobile-proxies/)
- [Integration Guides & API Tutorials](https://pxm2.io/guides/)
- [Contact Support](https://pxm2.io/contact/)

---

## License

MIT License. See [LICENSE](LICENSE) for details.
