nodriver-proxyhat 0.1.0__py3-none-any.whl

nodriver_proxyhat/__init__.py

@@ -0,0 +1,15 @@
+"""nodriver-proxyhat — route nodriver (undetected Chrome) through ProxyHat residential proxies."""
+
+from nodriver_proxyhat._auth import enable_proxy_auth
+from nodriver_proxyhat._resolve import ProxyHatConfigError, resolve_credentials
+from nodriver_proxyhat.proxy import proxyhat_auth, proxyhat_browser, proxyhat_browser_args
+
+__all__ = [
+    "ProxyHatConfigError",
+    "enable_proxy_auth",
+    "proxyhat_auth",
+    "proxyhat_browser",
+    "proxyhat_browser_args",
+    "resolve_credentials",
+]
+__version__ = "0.1.0"

nodriver_proxyhat/_auth.py

@@ -0,0 +1,55 @@
+"""Wire ProxyHat gateway authentication onto a nodriver tab over raw CDP.
+
+Chrome's ``--proxy-server`` flag can't carry a username/password, so a credentialed
+residential gateway needs another way to answer the proxy's auth challenge. nodriver
+speaks the Chrome DevTools Protocol directly, so we authenticate the CDP way:
+
+1. enable the ``Fetch`` domain with ``handle_auth_requests=True``,
+2. answer every ``Fetch.authRequired`` with the ProxyHat targeting username +
+   sub-user password via ``Fetch.continueWithAuth`` (``ProvideCredentials``),
+3. resume every other paused request with ``Fetch.continueRequest``.
+
+Enabling ``Fetch`` pauses *every* request (a ``requestPaused`` event), so the
+non-auth requests must be continued too or the page hangs waiting on us.
+
+This is the HTTP gateway path (port 8080) — CDP proxy auth answers the HTTP
+proxy's basic-auth challenge. ``nodriver`` is imported lazily so importing this
+module never requires it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nodriver import Tab
+
+
+async def enable_proxy_auth(tab: Tab, username: str, password: str) -> None:
+    """Register the CDP proxy-auth handlers on ``tab`` and enable ``Fetch``.
+
+    Adds a ``Fetch.authRequired`` handler that answers with ``username`` /
+    ``password`` and a ``Fetch.requestPaused`` handler that resumes normal
+    requests, then enables the Fetch domain with auth handling. Call once per tab
+    before navigating so the very first request is authenticated.
+    """
+    from nodriver import cdp
+
+    async def _on_auth_required(event: cdp.fetch.AuthRequired) -> None:
+        await tab.send(
+            cdp.fetch.continue_with_auth(
+                request_id=event.request_id,
+                auth_challenge_response=cdp.network.AuthChallengeResponse(
+                    response="ProvideCredentials",
+                    username=username,
+                    password=password,
+                ),
+            )
+        )
+
+    async def _on_request_paused(event: cdp.fetch.RequestPaused) -> None:
+        await tab.send(cdp.fetch.continue_request(request_id=event.request_id))
+
+    tab.add_handler(cdp.fetch.AuthRequired, _on_auth_required)
+    tab.add_handler(cdp.fetch.RequestPaused, _on_request_paused)
+    await tab.send(cdp.fetch.enable(handle_auth_requests=True))

nodriver_proxyhat/_resolve.py

@@ -0,0 +1,71 @@
+"""Gateway credential resolution for nodriver-proxyhat.
+
+Mirrors the other ProxyHat integrations: explicit ``username``/``password``
+(or ``PROXYHAT_USERNAME``/``PROXYHAT_PASSWORD``) win; otherwise an API key
+(``PROXYHAT_API_KEY``) looks up your sub-users via the official ``proxyhat`` SDK
+and picks an active one with remaining traffic — or the one named by ``sub_user``.
+Everything here except the sub-user lookup is offline.
+"""
+
+from __future__ import annotations
+
+import os
+
+from proxyhat import ProxyHat
+
+
+class ProxyHatConfigError(RuntimeError):
+    """Raised when ProxyHat credentials cannot be resolved."""
+
+
+def _env(name: str) -> str | None:
+    value = os.environ.get(name)
+    return value.strip() if value and value.strip() else None
+
+
+def resolve_credentials(
+    *,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    sub_user: str | None = None,
+) -> tuple[str, str]:
+    """Resolve a sub-user's ``(proxy_username, proxy_password)``.
+
+    Options win over environment variables. Precedence:
+
+    1. explicit ``username`` + ``password`` (``PROXYHAT_USERNAME`` / ``PROXYHAT_PASSWORD``)
+    2. ``api_key`` (``PROXYHAT_API_KEY``) → auto-pick an active sub-user, or the
+       one named by ``sub_user`` (``PROXYHAT_SUBUSER``).
+    """
+    username = username or _env("PROXYHAT_USERNAME")
+    password = password or _env("PROXYHAT_PASSWORD")
+    if username and password:
+        return username, password
+
+    api_key = api_key or _env("PROXYHAT_API_KEY")
+    if not api_key:
+        raise ProxyHatConfigError(
+            "nodriver-proxyhat: no credentials. Pass api_key (or PROXYHAT_API_KEY), "
+            "or username + password (PROXYHAT_USERNAME / PROXYHAT_PASSWORD)."
+        )
+
+    return _resolve_sub_user(api_key, sub_user or _env("PROXYHAT_SUBUSER"))
+
+
+def _resolve_sub_user(api_key: str, want: str | None) -> tuple[str, str]:
+    users = ProxyHat(api_key=api_key).sub_users.list()
+    usable = [u for u in users if not u.suspended_at and (u.traffic_limit == 0 or u.used_traffic < u.traffic_limit)]
+    if want:
+        chosen = next((u for u in users if u.uuid == want or u.name == want), None)
+    else:
+        chosen = usable[0] if usable else None
+
+    if chosen is None or not chosen.proxy_username or not chosen.proxy_password:
+        raise ProxyHatConfigError(
+            f'nodriver-proxyhat: no sub-user matched "{want}" (or it has no proxy credentials).'
+            if want
+            else "nodriver-proxyhat: no usable sub-user found (all suspended or out of traffic). "
+            "Create one, top up, or pass sub_user."
+        )
+    return chosen.proxy_username, chosen.proxy_password

nodriver_proxyhat/proxy.py

@@ -0,0 +1,162 @@
+"""Route a nodriver (undetected Chrome) browser through the ProxyHat gateway.
+
+nodriver launches Chrome with ``nodriver.start(browser_args=[...])``, but Chrome's
+``--proxy-server`` flag can't carry a username/password. nodriver gives raw CDP
+access, so the credentialed residential gateway is authenticated the CDP way:
+enable the Fetch domain with ``handle_auth_requests=True`` and answer
+``Fetch.authRequired`` with the ProxyHat targeting username + sub-user password
+(see :mod:`nodriver_proxyhat._auth`).
+
+Three entry points:
+
+- ``proxyhat_browser_args()`` — the ``--proxy-server`` launch flag for the gateway.
+- ``proxyhat_auth()`` — the ``(username, password)`` for wiring the CDP auth
+  handler yourself.
+- ``proxyhat_browser()`` — start Chrome with the flag applied *and* the CDP auth
+  handler already wired.
+
+This is the HTTP gateway (port 8080); CDP proxy auth applies to the HTTP proxy.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from proxyhat import (
+    PROXYHAT_GATEWAY,
+    PROXYHAT_PORT_HTTP,
+    build_proxy_username,
+)
+
+from nodriver_proxyhat._auth import enable_proxy_auth
+from nodriver_proxyhat._resolve import resolve_credentials
+
+if TYPE_CHECKING:
+    from nodriver import Browser
+
+# A browser session takes many steps against the same site, so pin one
+# residential IP for the whole session by default — keeps cookies and
+# fingerprint consistent. sticky=False rotates a fresh IP per connection.
+DEFAULT_STICKY = "30m"
+
+
+def proxyhat_browser_args(**_targeting: Any) -> list[str]:
+    """Return the Chrome launch args pointing nodriver at the ProxyHat gateway.
+
+    Just ``["--proxy-server=gate.proxyhat.com:8080"]`` — the HTTP gateway host and
+    port. Targeting (``country`` / ``region`` / ``city`` / ``sticky`` / ``filter``)
+    is *not* encoded here, because Chrome's ``--proxy-server`` can't carry it: it
+    lives in the CDP auth username built by :func:`proxyhat_auth` and applied by
+    :func:`proxyhat_browser`. Targeting keyword arguments are accepted (so you can
+    splat the same dict you pass to those) but do not change the returned flag.
+
+    Merge the result into your own ``nodriver.start(browser_args=[...])`` call and
+    wire auth yourself with :func:`proxyhat_auth` + ``enable_proxy_auth`` — or just
+    use :func:`proxyhat_browser`, which does both.
+    """
+    return [f"--proxy-server={PROXYHAT_GATEWAY}:{PROXYHAT_PORT_HTTP}"]
+
+
+def proxyhat_auth(
+    *,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    sub_user: str | None = None,
+    country: str | None = None,
+    region: str | None = None,
+    city: str | None = None,
+    sticky: bool | str | None = DEFAULT_STICKY,
+    filter: str | None = None,
+) -> tuple[str, str]:
+    """Resolve the ``(gateway_username, password)`` for the ProxyHat gateway.
+
+    Resolves credentials (``api_key`` / ``PROXYHAT_API_KEY`` auto-picks an active
+    sub-user, or pass explicit ``username`` / ``password``), then builds the
+    targeting username — geo and stickiness reflected — with the official
+    ``proxyhat`` SDK grammar. Feed the pair to a CDP ``Fetch.authRequired`` handler
+    (``ProvideCredentials``) if you're wiring nodriver yourself; otherwise
+    :func:`proxyhat_browser` does it for you.
+
+    Sticky vs rotating:
+
+    - ``sticky="30m"`` (default) or ``sticky=True`` pins one residential IP for
+      the session — recommended for a browser.
+    - ``sticky=False`` (or ``None``) rotates: a fresh residential IP per connection.
+    - ``sticky="2h"`` sets a custom session lifetime.
+
+    Geo/quality targeting: ``country`` (ISO code or ``"any"``), ``region``,
+    ``city``, ``filter`` (AI IP-quality tier).
+    """
+    user, pw = resolve_credentials(
+        api_key=api_key,
+        username=username,
+        password=password,
+        sub_user=sub_user,
+    )
+    # Build the targeting username once so a sticky session mints a single sid
+    # shared by every request the browser makes.
+    gateway_username = build_proxy_username(
+        user,
+        country=country,
+        region=region,
+        city=city,
+        sticky=sticky,
+        filter=filter,
+    )
+    return gateway_username, pw
+
+
+async def proxyhat_browser(
+    *,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    sub_user: str | None = None,
+    country: str | None = None,
+    region: str | None = None,
+    city: str | None = None,
+    sticky: bool | str | None = DEFAULT_STICKY,
+    filter: str | None = None,
+    **start_kwargs: Any,
+) -> Browser:
+    """Start a nodriver Chrome routed through ProxyHat with gateway auth wired.
+
+    Resolves credentials, calls ``nodriver.start(browser_args=[...], **start_kwargs)``
+    with the ``--proxy-server`` flag applied, then enables CDP ``Fetch`` on the
+    browser's main tab and registers a ``Fetch.authRequired`` handler that answers
+    with the ProxyHat targeting username + sub-user password. Returns the started
+    ``Browser`` — navigate with ``await browser.get(url)``.
+
+    Any extra keyword arguments (``headless``, ``user_data_dir``, ``sandbox``, …)
+    are forwarded to ``nodriver.start``; if you pass your own ``browser_args`` they
+    are merged with the ProxyHat flag. Sticky by default (one pinned IP for the
+    whole session); pass ``sticky=False`` for a rotating IP. See :func:`proxyhat_auth`
+    for the full targeting keyword set.
+
+    ``nodriver`` is imported lazily — install it (``pip install nodriver-proxyhat[nodriver]``)
+    to use this helper; :func:`proxyhat_browser_args` and :func:`proxyhat_auth` work
+    without it.
+    """
+    gateway_username, pw = proxyhat_auth(
+        api_key=api_key,
+        username=username,
+        password=password,
+        sub_user=sub_user,
+        country=country,
+        region=region,
+        city=city,
+        sticky=sticky,
+        filter=filter,
+    )
+
+    caller_args = start_kwargs.pop("browser_args", None) or []
+    browser_args = proxyhat_browser_args() + list(caller_args)
+
+    # Imported lazily: nodriver is an optional (peer) dependency, so importing
+    # this module never forces a Chrome/nodriver install.
+    import nodriver
+
+    browser = await nodriver.start(browser_args=browser_args, **start_kwargs)
+    await enable_proxy_auth(browser.main_tab, gateway_username, pw)
+    return browser

nodriver_proxyhat-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: nodriver-proxyhat
+Version: 0.1.0
+Summary: ProxyHat residential proxies for nodriver (undetected Chrome) — CDP proxy auth, sticky sessions, geo-targeting, rotation.
+Project-URL: Homepage, https://proxyhat.com
+Project-URL: Documentation, https://docs.proxyhat.com
+Project-URL: Repository, https://github.com/ProxyHatCom/nodriver-proxyhat
+Author-email: ProxyHat <support@proxyhat.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: browser-automation,cdp,nodriver,proxy,proxyhat,residential-proxy,sticky-session,undetected-chromedriver,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Requires-Dist: proxyhat>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: nodriver
+Requires-Dist: nodriver>=0.32; extra == 'nodriver'
+Description-Content-Type: text/markdown
+
+# nodriver-proxyhat
+
+Route [nodriver](https://github.com/ultrafunkamsterdam/nodriver) — the successor to undetected-chromedriver — through [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=nodriver) residential proxies. **Authenticated** gateway proxies wired straight into nodriver over CDP, plus a sticky residential IP pinned for the whole session, geo-targeting, and rotation.
+
+[![CI](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/ci.yml/badge.svg)](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/ci.yml)
+[![Compatible with nodriver latest](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/compat.yml/badge.svg)](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/compat.yml)
+[![PyPI](https://img.shields.io/pypi/v/nodriver-proxyhat)](https://pypi.org/project/nodriver-proxyhat/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why
+
+Chrome's `--proxy-server` flag **can't carry a username and password**, so pointing an undetected browser at a credentialed residential gateway normally means a manual CDP dance. And running a real browser from a datacenter IP gets flagged, CAPTCHA-walled, and blocked anyway — exactly what you're using nodriver to avoid.
+
+`nodriver-proxyhat` fixes both. It plugs ProxyHat's residential IPs (50M+ across 148+ countries) into nodriver and handles gateway auth the CDP way nodriver is built for: it enables the **Fetch** domain and answers the proxy's `Fetch.authRequired` challenge with your credentials. One pinned residential IP per session by default, so cookies and fingerprint stay consistent while your script works.
+
+## Install
+
+```bash
+pip install nodriver-proxyhat nodriver
+```
+
+`nodriver` is a peer dependency — bring your own version (and its Chrome). The `proxyhat_browser_args()` / `proxyhat_auth()` helpers work without it; `proxyhat_browser()` needs nodriver installed.
+
+## Quick start
+
+```python
+import nodriver as uc
+from nodriver_proxyhat import proxyhat_browser
+
+async def main():
+    # An API key (PROXYHAT_API_KEY) auto-selects an active residential sub-user:
+    browser = await proxyhat_browser(country="us")   # sticky US IP for the whole session
+    page = await browser.get("https://httpbin.org/ip")
+    print(await page.get_content())
+    browser.stop()
+
+uc.loop().run_until_complete(main())
+```
+
+Get an API key at [proxyhat.com](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=nodriver).
+
+`proxyhat_browser(...)` calls `nodriver.start(...)` for you and forwards any extra keyword arguments (`headless`, `user_data_dir`, `browser_args`, …) unchanged.
+
+## Credentials
+
+Pass them explicitly or via environment variables — options win over env:
+
+| Option | Env var | Notes |
+|---|---|---|
+| `api_key` | `PROXYHAT_API_KEY` | Auto-selects an active sub-user with remaining traffic |
+| `sub_user` | `PROXYHAT_SUBUSER` | Pick a specific sub-user by uuid or name (with an API key) |
+| `username` | `PROXYHAT_USERNAME` | Explicit gateway `proxy_username` (skips the API) |
+| `password` | `PROXYHAT_PASSWORD` | Explicit gateway `proxy_password` |
+
+## Targeting
+
+```python
+await proxyhat_browser(
+    country="us",      # ISO code or "any" (default)
+    region="california",
+    city="new_york",
+    filter="high",     # AI IP-quality tier
+    sticky="30m",      # session lifetime (default); sticky=False rotates every request
+    headless=True,     # any extra kwarg is forwarded to nodriver.start
+)
+```
+
+The same targeting keyword arguments work on `proxyhat_auth(...)`.
+
+### Sticky IP per session (default)
+
+A browser session takes many steps against the same site — logging in, clicking, scrolling. If the exit IP changed mid-session the site would see a user teleporting between cities and block it. So this package is **sticky by default**: one residential IP is pinned for the whole session (`sticky="30m"`, renewed as you work), keeping cookies and fingerprint coherent.
+
+Want a fresh IP on **every** request instead (e.g. many independent one-shot fetches)? Turn stickiness off:
+
+```python
+await proxyhat_browser(country="us", sticky=False)  # rotating residential IP per connection
+```
+
+Set a custom lifetime with `sticky="2h"`.
+
+## How authentication works
+
+nodriver takes the proxy host/port from `--proxy-server=gate.proxyhat.com:8080`, but a residential gateway also needs a username (the ProxyHat targeting string) and password. Since the flag can't carry them, `proxyhat_browser` uses nodriver's raw Chrome DevTools Protocol access instead:
+
+1. it enables the **Fetch** domain on the main tab with `handle_auth_requests=True`;
+2. it registers a `Fetch.authRequired` handler that answers with your targeting username + sub-user password via `Fetch.continueWithAuth` (`ProvideCredentials`);
+3. it resumes every other paused request with `Fetch.continueRequest` (enabling Fetch pauses all requests, so non-auth ones must be continued too).
+
+The targeting username (e.g. `<user>-country-us-sid-<id>-ttl-30m`) is built by the official [`proxyhat`](https://pypi.org/project/proxyhat/) SDK, so a sticky session mints a single session id shared across the run.
+
+This is the **HTTP gateway** (port 8080) — CDP proxy auth answers the HTTP proxy's basic-auth challenge.
+
+## Wiring it yourself
+
+Prefer to drive `nodriver.start()` your way? Grab the launch flag and the resolved credentials and wire the CDP handler yourself:
+
+```python
+import nodriver as uc
+from nodriver import cdp
+from nodriver_proxyhat import proxyhat_auth, proxyhat_browser_args, enable_proxy_auth
+
+async def main():
+    username, password = proxyhat_auth(country="de", sticky="1h")
+
+    browser = await uc.start(browser_args=proxyhat_browser_args() + ["--headless=new"])
+    # enable_proxy_auth does the Fetch.enable + authRequired dance for you:
+    await enable_proxy_auth(browser.main_tab, username, password)
+
+    page = await browser.get("https://httpbin.org/ip")
+    print(await page.get_content())
+    browser.stop()
+
+uc.loop().run_until_complete(main())
+```
+
+`proxyhat_browser_args()` returns `["--proxy-server=gate.proxyhat.com:8080"]`; `proxyhat_auth()` returns the `(username, password)` for a `Fetch.authRequired` handler.
+
+## License
+
+MIT © [ProxyHat](https://proxyhat.com)

nodriver_proxyhat-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+nodriver_proxyhat/__init__.py,sha256=tHzV8AnV96Emh-Iqg3u9Kw6E_zSqu1h4Dum5qwDI2xE,517
+nodriver_proxyhat/_auth.py,sha256=RKd1v968NI6cvKyGUd6qoQxI91uUdsBixCQiXshHPE8,2345
+nodriver_proxyhat/_resolve.py,sha256=tfsq3e743i7zOAMxSXZm1T0l630xAe_OIIqi0zQaHHE,2680
+nodriver_proxyhat/proxy.py,sha256=uDZ_wLrN31MOTJWxe8BifmlfjVGwzSEXR2hkKw60VrA,6364
+nodriver_proxyhat-0.1.0.dist-info/METADATA,sha256=77XI-LaRzcYO7wg6rwEbat-qzLa4_pmvmbxPNJPxyv8,7587
+nodriver_proxyhat-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+nodriver_proxyhat-0.1.0.dist-info/licenses/LICENSE,sha256=_yoC1-ij-yJ3LPoEUetu723duo_t9XcI08QcSS6jSiQ,1065
+nodriver_proxyhat-0.1.0.dist-info/RECORD,,

nodriver_proxyhat-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nodriver_proxyhat-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProxyHat
+
+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.