patchright-difz 0.3.0

Patchright Python wrapper with optional Turnstile auto-click helper.

patchright-difz

Patchright Python wrapper with an optional Turnstile helper.

Install

pip install patchright-difz

Sync usage

from patchright_difz.sync_api import sync_playwright

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context(
        ".profile",
        headless=False,
        channel="chrome",
        no_viewport=True,
        turnstile=True,
    )
    page = context.new_page()
    page.goto("https://example.com")

Async usage

from patchright_difz.async_api import async_playwright

async with async_playwright() as p:
    context = await p.chromium.launch_persistent_context(
        ".profile",
        headless=False,
        channel="chrome",
        no_viewport=True,
        turnstile=True,
    )
    page = await context.new_page()
    await page.goto("https://example.com")

page.evaluate, frame.evaluate, locator evaluate helpers, and handle evaluate helpers default to the page main world in this wrapper. If you need Patchright's isolated world for a specific call, pass isolated_context=True.

The Turnstile helper uses Patchright locators for fallback detection, so it can also pick up challenge candidates rendered inside closed shadow roots.

When headless=True is used without a custom user_agent, the wrapper sets a normal Chrome user agent before the first request. This applies to launch_persistent_context, browser.new_context, and browser.new_page. Set PATCHRIGHT_DIFZ_HEADLESS_USER_AGENT=0 to keep Patchright's default headless user agent, or set it to a full user-agent string to override the default.

Configure Turnstile

context = p.chromium.launch_persistent_context(
    ".profile",
    headless=False,
    channel="chrome",
    no_viewport=True,
    turnstile={
        "timeout_ms": 5000,
        "interval_ms": 2000,
        "logger": print,
    },
)

Camel-case option names from the npm package are also accepted: timeoutMs, intervalMs, and maxCandidatesPerSelector.

Manual usage

from patchright_difz.sync_api import check_turnstile, sync_playwright

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context(
        ".profile",
        headless=False,
        channel="chrome",
        no_viewport=True,
    )
    page = context.new_page()
    page.goto("https://example.com")
    check_turnstile(page)

Publish

python scripts/publish.py

The command builds, creates a v<version> git tag, pushes to GitHub, and lets the GitHub Actions workflow publish to PyPI through Trusted Publishing.