solari-browser 0.1.1__tar.gz

solari_browser-0.1.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+target/
+node_modules/
+dist/

solari_browser-0.1.1/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: solari-browser
+Version: 0.1.1
+Summary: Python SDK for Solari Browser — managed, stealthy remote Chromium over the Playwright wire protocol / raw CDP.
+Project-URL: Homepage, https://getsolari.com
+Author: Solari
+License: Apache-2.0
+Keywords: automation,browser,cdp,playwright,scraping,solari,stealth
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: patchright<1.60,>=1.59
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# solari-browser (Python)
+
+Python SDK for **Solari Browser** — managed, stealth-hardened remote Chromium as
+an API, driven over the Playwright wire protocol (or raw CDP). A faithful port of
+the TypeScript `@solarisdk/browser` package; class, method, and field names match
+it one-for-one (snake_case where TS uses camelCase).
+
+The browser runs remotely on Solari's pool — `pip install` pulls the driver only;
+you do **not** run `patchright install chromium` locally.
+
+## Install
+
+```sh
+pip install solari-browser
+```
+
+## Quickstart
+
+```python
+import asyncio, os
+from solari_browser import Solari
+
+async def main():
+    solari = Solari(api_key=os.environ["SOLARI_API_KEY"])
+    browser = await solari.launch(stealth=True)   # managed, stealth-hardened Chromium
+    page = await browser.new_page()
+    await page.goto("https://example.com")
+    print(await page.title())
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Sessions
+
+Drive a session yourself instead of `launch()`:
+
+```python
+solari = Solari(api_key=os.environ["SOLARI_API_KEY"])
+session = await solari.sessions.create(stealth=True, proxy="smart")
+# ... connect over the session's CDP/WS endpoint ...
+await solari.close()
+```
+
+`Solari(...)` accepts `api_key`, `region` (default `us-west`), and `base_url`
+(default `https://api.getsolari.com`).
+
+## Docs
+
+Full reference and language guides: <https://getsolari.com>

solari_browser-0.1.1/README.md

@@ -0,0 +1,50 @@
+# solari-browser (Python)
+
+Python SDK for **Solari Browser** — managed, stealth-hardened remote Chromium as
+an API, driven over the Playwright wire protocol (or raw CDP). A faithful port of
+the TypeScript `@solarisdk/browser` package; class, method, and field names match
+it one-for-one (snake_case where TS uses camelCase).
+
+The browser runs remotely on Solari's pool — `pip install` pulls the driver only;
+you do **not** run `patchright install chromium` locally.
+
+## Install
+
+```sh
+pip install solari-browser
+```
+
+## Quickstart
+
+```python
+import asyncio, os
+from solari_browser import Solari
+
+async def main():
+    solari = Solari(api_key=os.environ["SOLARI_API_KEY"])
+    browser = await solari.launch(stealth=True)   # managed, stealth-hardened Chromium
+    page = await browser.new_page()
+    await page.goto("https://example.com")
+    print(await page.title())
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Sessions
+
+Drive a session yourself instead of `launch()`:
+
+```python
+solari = Solari(api_key=os.environ["SOLARI_API_KEY"])
+session = await solari.sessions.create(stealth=True, proxy="smart")
+# ... connect over the session's CDP/WS endpoint ...
+await solari.close()
+```
+
+`Solari(...)` accepts `api_key`, `region` (default `us-west`), and `base_url`
+(default `https://api.getsolari.com`).
+
+## Docs
+
+Full reference and language guides: <https://getsolari.com>

solari_browser-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "solari-browser"
+version = "0.1.1"
+description = "Python SDK for Solari Browser — managed, stealthy remote Chromium over the Playwright wire protocol / raw CDP."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Solari" }]
+keywords = ["solari", "browser", "playwright", "cdp", "stealth", "automation", "scraping"]
+dependencies = [
+    "httpx>=0.24",
+    # patchright is Playwright-with-stealth-patches. The POOL runs patchright and
+    # the Playwright wire protocol embeds the client version in the User-Agent;
+    # the server rejects a mismatch with HTTP 428.
+    #
+    # The gate compares MAJOR.MINOR ONLY — patchright-core's
+    # lib/remote/playwrightServer.js does:
+    #     received = clientVersion.split(".").slice(0, 2).join(".")
+    #     expected = getPlaywrightVersion(/* majorMinorOnly */ true)
+    # so any 1.59.x client talks to the pool's 1.59.3 (node) server. This range is
+    # therefore pinned to the pool's major.minor, NOT to an exact version — PyPI
+    # has no 1.59.3 (the node and python patchright release trains differ; PyPI's
+    # 1.59 line tops out at 1.59.1).
+    #
+    # If the pool's `patchright` pin moves to 1.60/1.61, this MUST move with it or
+    # every launch() 428s. Asserted by scripts/check-sdk-version-pin.mjs.
+    "patchright>=1.59,<1.60",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.1"]
+
+[project.urls]
+Homepage = "https://getsolari.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["solari_browser"]
+
+[tool.ruff]
+line-length = 100
+

solari_browser-0.1.1/solari_browser/__init__.py

@@ -0,0 +1,60 @@
+"""Solari Browser — Python SDK.
+
+Managed, stealthy remote Chromium over the Playwright wire protocol / raw CDP.
+
+    import asyncio
+    from solari_browser import Solari
+
+    async def main():
+        async with Solari(api_key="slr_live_...") as solari:
+            async with await solari.launch(stealth=True) as browser:
+                page = await browser.new_page()
+                await page.goto("https://example.com")
+                print(await page.title())
+
+    asyncio.run(main())
+"""
+
+from .browser_session import BrowserSession
+from .client import Solari, derive_cdp_from_ws
+from .errors import (
+    BROWSER_UNHEALTHY,
+    CONCURRENCY_LIMIT_EXCEEDED,
+    FEATURE_REQUIRES_PLAN,
+    PLAN_LIMIT_EXCEEDED,
+    SolariError,
+)
+from .types import (
+    DEFAULT_REGION,
+    REGION_URLS,
+    UNSET,
+    Profile,
+    ProxyRequest,
+    ReplayUrl,
+    ResolvedProxyConfig,
+    SaveResult,
+    Session,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Solari",
+    "BrowserSession",
+    "SolariError",
+    "Session",
+    "Profile",
+    "ProxyRequest",
+    "ResolvedProxyConfig",
+    "ReplayUrl",
+    "SaveResult",
+    "UNSET",
+    "REGION_URLS",
+    "DEFAULT_REGION",
+    "derive_cdp_from_ws",
+    "FEATURE_REQUIRES_PLAN",
+    "CONCURRENCY_LIMIT_EXCEEDED",
+    "PLAN_LIMIT_EXCEEDED",
+    "BROWSER_UNHEALTHY",
+    "__version__",
+]

solari_browser-0.1.1/solari_browser/browser_session.py

@@ -0,0 +1,94 @@
+"""BrowserSession — a connected browser + its Solari session. Mirrors sdk/src/browser-session.ts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, List, Optional
+
+from .types import ResolvedProxyConfig, Session
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import Solari
+
+
+class BrowserSession:
+    """Wraps a patchright `Browser` and the Solari session backing it.
+
+    `close()` closes the browser AND releases the session — a browser close alone
+    would leave the slot held until its plan deadline.
+    """
+
+    def __init__(self, client: "Solari", session: Session, browser: Any) -> None:
+        self._client = client
+        self._session = session
+        self._browser = browser
+        self._closed = False
+
+    @property
+    def id(self) -> str:
+        return self._session.id
+
+    @property
+    def expires_at(self) -> str:
+        """ISO 8601 UTC deadline; the session auto-releases at this point."""
+        return self._session.expires_at
+
+    @property
+    def proxy(self) -> Optional[ResolvedProxyConfig]:
+        return self._session.proxy
+
+    @property
+    def ws_endpoint(self) -> str:
+        """Upstream Playwright wire-protocol endpoint."""
+        return self._session.ws_endpoint
+
+    @property
+    def cdp_endpoint(self) -> str:
+        """Upstream raw-CDP endpoint.
+
+        NOTE: driving the browser over raw CDP bypasses the pool's Playwright-path
+        input humanization (see CLAUDE.md) — relevant if you care about stealth.
+        """
+        return self._session.cdp_endpoint
+
+    @property
+    def session(self) -> Session:
+        return self._session
+
+    @property
+    def raw(self) -> Any:
+        """The underlying patchright `Browser`."""
+        return self._browser
+
+    def is_connected(self) -> bool:
+        return bool(self._browser.is_connected())
+
+    @property
+    def version(self) -> str:
+        return str(self._browser.version)
+
+    def contexts(self) -> List[Any]:
+        """Existing browser contexts. The default context is `contexts()[0]`."""
+        return list(self._browser.contexts)
+
+    async def new_context(self, **kwargs: Any) -> Any:
+        return await self._browser.new_context(**kwargs)
+
+    async def new_page(self) -> Any:
+        return await self._browser.new_page()
+
+    async def close(self) -> None:
+        """Close the browser and release the session. Idempotent."""
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            await self._browser.close()
+        except Exception:  # noqa: BLE001 - releasing the slot matters more
+            pass
+        await self._client.sessions.release_and_wait(self._session.id)
+
+    async def __aenter__(self) -> "BrowserSession":
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self.close()