vinyzu-archive/Botright

Overview

Botright is an async Python library that wraps Playwright to make an automated browser harder to detect. You replace the browser initialisation with await botright.Botright() and await client.new_browser(proxy=...), and keep writing ordinary Playwright code. Underneath, it launches a Chromium-family browser already installed on your machine (not Playwright’s bundled build), applies a fingerprint sampled from real Chrome data, aligns timezone and geolocation with the proxy’s exit IP, moves the mouse along randomised Bézier curves, and adds page.solve_hcaptcha() and page.solve_recaptcha() methods backed by local vision models.

It is not a scraper in the extraction sense. There are no LLM calls, no HTML-to-Markdown conversion, no selectors-as-schema, and no crawler. You get the browser you would use underneath such a tool. The “AI” in its description is computer-vision CAPTCHA solving from two of the author’s other packages, hcaptcha_challenger and recognizer.

Treat the project as frozen. The pinned repository lives under a vinyzu-archive organisation, the version is 0.5.1, the last changelog entry is from January 2024, and the requirements pin playwright==1.42.0. The README marks hCaptcha solving as “outdated” and GeeTest as “Currently Not Available”. The code agrees: solve_geetest raises NotImplementedError.

Architecture

flowchart LR
  U["Your async code"] --> BR["Botright client"]
  BR --> ENG["get_browser_engine (local Chromium)"]
  BR --> NB["new_browser(proxy)"]
  NB --> PM["ProxyManager: IP + geo lookup"]
  NB --> FK["Faker: chrome-fingerprints"]
  NB --> CTX["launch_persistent_context"]
  CTX --> BC["BrowserContext wrapper"]
  BC --> PG["Page wrapper"]
  PG --> CDP["CDP UA + client hints override"]
  PG --> HM["Humanized Mouse / Keyboard"]
  PG --> HC["hCaptcha (hcaptcha_challenger)"]
  PG --> RC["reCAPTCHA (recognizer)"]

Component	Path	Role
Client	botright/botright.py	Botright async object: Chrome flags, engine discovery, new_browser, cleanup
Proxy manager	botright/modules/proxy_manager.py	Parses proxy strings, checks the exit IP, looks up country, coordinates and timezone
Fingerprints	botright/modules/faker.py	Gets a fingerprint from chrome-fingerprints and a locale from the proxy country
Context wrapper	botright/playwright_mock/browser.py	Builds launch arguments, persistent context, image blocking, response cache
Page wrapper	botright/playwright_mock/page.py	CDP UA override, CAPTCHA methods, humanised click/type overrides
Input	botright/playwright_mock/mouse.py, keyboard.py	Bézier mouse paths and jittered key delays
hCaptcha	botright/modules/hcaptcha.py	Drives hcaptcha_challenger.AgentT, optional rqdata injection
Other wrappers	botright/playwright_mock/	Locator, Frame, FrameLocator, handles and routes re-wrapped so behaviour carries through

How a request flows

1. Client init. Botright.__ainit__ first runs hcaptcha_challenger.install(upgrade=True) to fetch or refresh model assets. It then starts Playwright (or undetected_playwright when use_undetected_playwright=True), picks a browser, deletes leftover botright-* temp dirs, and builds a list of about 70 Chrome flags. These include --disable-blink-features=AutomationControlled and WebRTC disable_non_proxied_udp, plus --fingerprinting-canvas-image-data-noise when canvas spoofing is on (botright.py).
2. Engine choice. get_browser_engine uses pybrowsers to find an installed browser. It tries chromium first (the author recommends Ungoogled Chromium), then chrome, then any non-Firefox/Edge/Opera/IE browser. It raises if none is found (botright.py).
3. Proxy check. new_browser awaits ProxyManager, which accepts ip:port, user:pass@ip:port and colon-separated four-part forms. It asks five what-is-my-IP services for the exit IP through the proxy, then four geo-IP services for country, latitude, longitude and timezone. With no proxy, the same lookups describe your own IP (proxy_manager.py).
4. Fingerprint. Faker concurrently samples a ChromeFingerprint and maps the proxy country code to a locale. An unknown country raises ValueError("Proxy Country not supported") (faker.py).
5. Launch. browser.new_browser passes the fingerprint’s user agent, screen and viewport, the proxy’s timezone and geolocation, color_scheme="dark", proxy credentials and ignore_default_args=["--enable-automation"] to launch_persistent_context with a fresh temp profile and the local browser’s executable (browser.py). It then grants notification and geolocation permissions (botright.py).
6. Page setup. new_page opens a CDP session and sends both Emulation.setUserAgentOverride and Network.setUserAgentOverride with full client-hints metadata (brands, full version list, platform, architecture, bitness, model) from the fingerprint (page.py).
7. Interaction. page.click(selector) waits for the element, takes its bounding box, and calls Mouse.click. That moves along a humanised curve from the last cursor position, pauses 200 to 400 ms, then presses and releases (page.py, mouse.py).

Key components

Playwright mock layer

Each wrapper subclasses the Playwright class, adopts the original’s _impl_obj, keeps the original methods as _origin_*, and overrides the ones that return other Playwright objects. That way objects reached through page.locator(...) or page.frames are Botright types too. Route handlers are proxied so callbacks receive wrapped Route/Request objects. With use_undetected_playwright, methods that depend on the CDP Runtime domain (expose_function, expose_binding, expect_console_message) raise NotSupportedError (browser.py). This works, but it is coupled tightly to Playwright internals, which is one reason the dependency is pinned.

Human-like input

HumanizeMouseTrajectory (adapted from HumanCursor) picks two random knots within 80 px of the straight path, builds a Bézier curve, adds Gaussian distortion, and tweens to 100 points with an ease-out. Each point becomes one mouse.move (mouse.py). Keyboard.type sends one character at a time with 50 to 150 ms delays by default (keyboard.py). Humanisation is always on. The user_action_layer flag only injects a full-screen canvas that draws coloured dots where the mouse moves and clicks. It is a debugging overlay, not a stealth feature.

CAPTCHA solving

hCaptcha.solve_hcaptcha clicks the checkbox through AgentT, retries up to seven rounds (refreshing on a backcall), and returns the pass token. If you give it rq_data, it first intercepts hcaptcha.com/getcaptcha/** and re-posts the request with that rqdata (hcaptcha.py). On failure it returns an error string (“Exceeded maximum retry times…”), not None, so check the result before using it as a token. solve_recaptcha delegates to recognizer’s AsyncChallenger. solve_geetest raises NotImplementedError, even though a 368-line geetest.py and a TorchScript model still ship in the package (page.py).

Bandwidth helpers

block_images=True aborts image requests by extension and by resource type. cache_responses=True serves documents, stylesheets, images, fonts and media from an in-memory dict keyed by URL, shared across all browsers of one client (browser.py). Caching document responses means a second goto to the same URL replays stale HTML.

Extending it

• Existing Playwright code. Everything after new_browser() is the Playwright async API, so extraction is up to you: page.content(), locators, or a downstream LLM extractor.
• Launch overrides. Extra keyword arguments to new_browser are merged over Botright’s launch arguments, so you can override locale, viewport or color_scheme.
• Stealth knobs. mask_fingerprint=False keeps the real UA and screen (the README says one tough site only passes this way). spoof_canvas, headless and use_undetected_playwright are constructor flags.
• Concurrency. Not thread-safe. Use one client per thread, or several pages and browsers with asyncio.gather.

Running it

• pip install botright, then playwright install. You also need a locally installed Chromium or Chrome; Ungoogled Chromium is recommended for canvas noise.
• Python 3.8+, async only. The default is a visible window (headless=False).
• The first run downloads hcaptcha_challenger assets, and every client start calls install(upgrade=True) again.
• Each new_browser call makes outbound requests to public IP and geo-IP services (ipify, ip-api.com, ipapi.co and others). Plan for those in locked-down networks.

Strengths and caveats

• Strength: coherent identity. UA string, client hints, screen, timezone and geolocation all come from one fingerprint and the proxy’s real exit location, rather than being randomised independently.
• Strength: drop-in API. Thorough wrapping means existing Playwright scripts mostly just work, with humanised input for free.
• Strength: local CAPTCHA solving. hCaptcha and reCAPTCHA image challenges are attempted with no paid solver API.
• Caveat: abandoned and pinned. The repository is archived, it is tied to Playwright 1.42 internals, GeeTest is disabled, and hCaptcha is flagged as outdated. Detection vendors have moved on since 2024, so the README’s pass table is historical.
• Caveat: locale inconsistency. The browser locale and Accept-Language are hard-coded to en-US, whatever the proxy country. The computed per-country locale is never applied, and many of its codes are invalid anyway (sp-ES, po-BR, ar-IL). A German proxy therefore shows Berlin time with US English.
• Caveat: small bugs. Locator.click reads the bounding box before scroll_into_view_if_needed and clicks the stale coordinates. solve_hcaptcha returns an error string on failure. An unsupported proxy country aborts new_browser.
• Caveat: not an extraction tool. No LLM, content cleaning, crawling, rate limiting or proxy rotation. Pair it with something else for the data side.

Sources: code at 6e64fed, deepwiki-open wiki (12 pages), OpenDeepWiki wiki (9 pages), verified Q&A.

botright_client = await botright.Botright(headless=False, block_images=True, cache_responses=False, ...)
browser = await botright_client.new_browser(proxy="user:pass@ip:port")
page = await browser.new_page()
await page.goto("https://example.com")
await page.solve_hcaptcha()  # custom method
await botright_client.close()