Metadata-Version: 2.4
Name: rayobrowse
Version: 2.3.0
Summary: Python SDK for rayobrowse, the Rayobyte cloud stealth Chromium browser
Author-email: Rayobyte <support@rayobyte.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://rayobyte.com
Project-URL: Documentation, https://docs.rayobyte.com/rayobrowse/
Keywords: browser,automation,stealth,scraping,playwright,anti-detect,fingerprint
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25

# rayobrowse

Python SDK for [rayobrowse](https://docs.rayobyte.com/rayobrowse/), the Rayobyte
cloud stealth Chromium browser. The SDK asks the gateway at
`https://browser.rayobyte.com` for a browser and returns its CDP WebSocket URL,
which you pass to Playwright, Puppeteer, or any other CDP client.

## Installation

```bash
pip install rayobrowse playwright && playwright install
```

Python 3.10 or newer.

## Quick start

```python
from rayobrowse import Rayobrowse
from playwright.sync_api import sync_playwright

PROXY = "http://USERNAME:PASSWORD@us-east.gw.rayobyte.com:8000"

client = Rayobrowse(endpoint="https://browser.rayobyte.com", api_key="rb_live_YOUR_KEY")
ws_url = client.connect_url(os="windows", proxy=PROXY)

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(ws_url)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

client.close()
```

Every `connect_url()` call needs a `proxy`. Without one the gateway returns
`400 PROXY_REQUIRED` and the SDK raises `BrowserCreateError`.

`endpoint` defaults to `https://browser.rayobyte.com`, or to the
`RAYOBYTE_ENDPOINT` environment variable when it is set.

`client.close()` closes the browser from the most recent `connect_url()` call.
An open session keeps running until its `max_lifetime` ends.

## Live view

```python
ws_url = client.connect_url(os="windows", proxy=PROXY, vnc=True)
print(f"CDP:  {ws_url}")
print(f"Live: {client.last_vnc_url}")
```

## Errors

A launch can be refused for two different limits, and the SDK raises a
different exception for each:

```python
from rayobrowse import BrowserCreateError, ConcurrencyLimitError, RateLimitError

try:
    ws_url = client.connect_url(os="windows", proxy=PROXY)
except ConcurrencyLimitError as e:   # all your concurrent browsers are running
    print(f"{e.active}/{e.limit} running, retry in {e.retry_after}s")
except RateLimitError as e:          # too many launches in the last minute
    print(f"Rate limited, retry in {e.retry_after}s")
except BrowserCreateError as e:     # anything else, e.g. 401 for a bad key
    print(f"Launch failed: {e}")
```

## Documentation

- [rayobrowse documentation](https://docs.rayobyte.com/rayobrowse/)
- [Python quickstart](https://docs.rayobyte.com/rayobrowse/sdks/python/quickstart/)
- [Support](mailto:support@rayobyte.com)
