hyperbrowser 0.93.4__tar.gz → 1.1.0__tar.gz

{hyperbrowser-0.93.4 → hyperbrowser-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 0.93.4
+Version: 1.1.0
 Summary: Python SDK for hyperbrowser
 License: MIT
 License-File: LICENSE
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: httpx (>=0.23.0,<1)
 Requires-Dist: jsonref (>=1.1.0)
 Requires-Dist: pydantic (>=2.0,<3)
+Requires-Dist: typing-extensions (>=4.0,<5)
 Requires-Dist: websockets (>=13,<16)
 Project-URL: Homepage, https://github.com/hyperbrowserai/python-sdk
 Project-URL: Repository, https://github.com/hyperbrowserai/python-sdk
@@ -41,6 +42,12 @@ It can be installed from `pypi` by running :
 pip install hyperbrowser
 ```
 
+The browser-control examples below also use Playwright:
+
+```shell
+pip install playwright
+```
+
 ## Configuration
 
 Both the sync and async client follow similar configuration params
@@ -56,12 +63,76 @@ Profile names must match `^[A-Za-z0-9._-]+$`.
 
 ## Usage
 
+Hyperbrowser 1.0 accepts plain dictionaries for request parameters. Method
+signatures use `TypedDict` definitions, so editors can autocomplete keys at
+every nested level:
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+
+# Preferred in 1.0: autocomplete works directly in the dictionary.
+session = client.sessions.create(
+    {
+        "use_stealth": True,
+        "screen": {"width": 1920, "height": 1080},
+    }
+)
+```
+
+Browser sessions can also use an outbound network policy. Omitting these fields
+keeps the default unrestricted behavior:
+
+```python
+session = client.sessions.create(
+    {
+        "allow_internet_access": False,
+        "allow_out": ["example.com"],
+        "deny_out": ["0.0.0.0/0"],
+    }
+)
+```
+
+Direct browser policies accept domains, IPv4 addresses, and CIDR ranges in
+`allow_out`; `deny_out` accepts IPv4 addresses and CIDR ranges. With a proxy,
+allow rules must be domains and the only supported deny rule is `0.0.0.0/0`.
+
+Existing Pydantic request classes remain accepted, so upgrading does not require
+an immediate rewrite:
+
+```python
+from hyperbrowser.models import CreateSessionParams, ScreenConfig
+
+session = client.sessions.create(
+    CreateSessionParams(
+        use_stealth=True,
+        screen=ScreenConfig(width=1920, height=1080),
+    )
+)
+```
+
+Import request annotations from `hyperbrowser.types` when a named variable is
+useful. The same names under `hyperbrowser.models` refer to the legacy Pydantic
+request classes. Responses remain Pydantic models.
+
+JSON Schema fields accept raw schema values, including object schemas with
+`$defs`, `$ref`, or custom keywords, and boolean schemas where the API supports
+them. Those schemas and other user-owned mappings are preserved as data; only
+SDK-owned request keys are translated to their API aliases. Schema fields
+documented as accepting a model class can also generate a schema from a Pydantic
+model.
+
+See the
+[Hyperbrowser Python SDK 1.0 migration guide](https://hyperbrowser.ai/docs/sdks/python-1-0-migration)
+for the complete compatibility details and migration checklist.
+
 ### Async
 
 ```python
 import asyncio
-from pyppeteer import connect
 from hyperbrowser import AsyncHyperbrowser
+from playwright.async_api import async_playwright
 
 HYPERBROWSER_API_KEY = "test-key"
 
@@ -69,29 +140,22 @@ async def main():
     async with AsyncHyperbrowser(api_key=HYPERBROWSER_API_KEY) as client:
         session = await client.sessions.create()
 
-        ws_endpoint = session.ws_endpoint
-        browser = await connect(browserWSEndpoint=ws_endpoint, defaultViewport=None)
-
-        # Get pages
-        pages = await browser.pages()
-        if not pages:
-            raise Exception("No pages available")
-
-        page = pages[0]
+        try:
+            async with async_playwright() as playwright:
+                browser = await playwright.chromium.connect_over_cdp(
+                    session.ws_endpoint
+                )
+                context = browser.contexts[0]
+                page = context.pages[0]
 
-        # Navigate to a website
-        print("Navigating to Hacker News...")
-        await page.goto("https://news.ycombinator.com/")
-        page_title = await page.title()
-        print("Page title:", page_title)
-
-        await page.close()
-        await browser.disconnect()
-        await client.sessions.stop(session.id)
-        print("Session completed!")
+                print("Navigating to Hacker News...")
+                await page.goto("https://news.ycombinator.com/")
+                print("Page title:", await page.title())
+        finally:
+            await client.sessions.stop(session.id)
 
 # Run the asyncio event loop
-asyncio.get_event_loop().run_until_complete(main())
+asyncio.run(main())
 ```
 ### Sync
 
@@ -141,17 +205,16 @@ The sync and async clients expose the same sandbox APIs through `client.sandboxe
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams
 
 client = Hyperbrowser(api_key="test-key")
 sandbox = client.sandboxes.create(
-    CreateSandboxParams(
-        image_name="node",
-        cpu=4,
-        memory_mib=4096,
-        disk_mib=8192,
-        exposed_ports=[SandboxExposeParams(port=3000, auth=True)],
-    )
+    {
+        "image_name": "node",
+        "cpu": 2,
+        "memory_mib": 2048,
+        "disk_mib": 8192,
+        "exposed_ports": [{"port": 3000, "auth": True}],
+    }
 )
 
 print(sandbox.exposed_ports[0].browser_url)
@@ -166,25 +229,24 @@ client.close()
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, CreateVolumeParams, SandboxVolumeMount
 
 client = Hyperbrowser(api_key="test-key")
 
-volume = client.volumes.create(CreateVolumeParams(name="project-cache"))
+volume = client.volumes.create({"name": "project-cache"})
 all_volumes = client.volumes.list()
 same_volume = client.volumes.get(volume.id)
 
 sandbox = client.sandboxes.create(
-    CreateSandboxParams(
-        image_name="node",
-        mounts={
-            "/workspace/cache": SandboxVolumeMount(
-                id=same_volume.id,
-                type="rw",
-                shared=True,
-            )
+    {
+        "image_name": "node",
+        "mounts": {
+            "/workspace/cache": {
+                "id": same_volume.id,
+                "type": "rw",
+                "shared": True,
+            }
         },
-    )
+    }
 )
 
 sandbox.stop()
@@ -195,17 +257,16 @@ client.close()
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import SandboxListParams
 
 client = Hyperbrowser(api_key="test-key")
 result = client.sandboxes.list(
-    SandboxListParams(
-        status="active",
-        search="sandbox",
-        start=1711929600000,
-        end=1712016000000,
-        limit=20,
-    )
+    {
+        "status": "active",
+        "search": "sandbox",
+        "start": 1711929600000,
+        "end": 1712016000000,
+        "limit": 20,
+    }
 )
 
 for sandbox in result.sandboxes:
@@ -216,11 +277,10 @@ for sandbox in result.sandboxes:
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import SandboxSnapshotListParams
 
 client = Hyperbrowser(api_key="test-key")
 snapshots = client.sandboxes.list_snapshots(
-    SandboxSnapshotListParams(image_name="node", status="created", limit=10)
+    {"image_name": "node", "status": "created", "limit": 10}
 )
 ```
 
@@ -228,16 +288,13 @@ snapshots = client.sandboxes.list_snapshots(
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams
 
 client = Hyperbrowser(api_key="test-key")
 sandbox = client.sandboxes.create(
-    CreateSandboxParams(
-        image_name="node", cpu=2, memory_mib=2048, disk_mib=8192
-    )
+    {"image_name": "node", "cpu": 2, "memory_mib": 2048, "disk_mib": 8192}
 )
 
-result = sandbox.expose(SandboxExposeParams(port=8080, auth=True))
+result = sandbox.expose({"port": 8080, "auth": True})
 print(result.url, result.browser_url)
 
 sandbox.unexpose(8080)
@@ -247,23 +304,19 @@ sandbox.unexpose(8080)
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, SandboxFileWriteEntry
 
 client = Hyperbrowser(api_key="test-key")
-sandbox = client.sandboxes.create(CreateSandboxParams(image_name="node"))
+sandbox = client.sandboxes.create({"image_name": "node"})
 
 sandbox.files.write(
     [
-        SandboxFileWriteEntry(
-            path="/tmp/config.json",
-            data='{"debug":true}\n',
-            append=True,
-            mode="600",
-        ),
-        SandboxFileWriteEntry(
-            path="/tmp/blob.bin",
-            data=b"\x00\x01\x02",
-        ),
+        {
+            "path": "/tmp/config.json",
+            "data": '{"debug":true}\n',
+            "append": True,
+            "mode": "600",
+        },
+        {"path": "/tmp/blob.bin", "data": b"\x00\x01\x02"},
     ]
 )
 ```
@@ -272,11 +325,10 @@ sandbox.files.write(
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, SandboxTerminalCreateParams
 
 client = Hyperbrowser(api_key="test-key")
-sandbox = client.sandboxes.create(CreateSandboxParams(image_name="node"))
-terminal = sandbox.terminal.create(SandboxTerminalCreateParams(command="bash"))
+sandbox = client.sandboxes.create({"image_name": "node"})
+terminal = sandbox.terminal.create({"command": "bash"})
 
 connection = terminal.attach(cursor=10)
 for event in connection.events():

{hyperbrowser-0.93.4 → hyperbrowser-1.1.0}/README.md

@@ -15,6 +15,12 @@ It can be installed from `pypi` by running :
 pip install hyperbrowser
 ```
 
+The browser-control examples below also use Playwright:
+
+```shell
+pip install playwright
+```
+
 ## Configuration
 
 Both the sync and async client follow similar configuration params
@@ -30,12 +36,76 @@ Profile names must match `^[A-Za-z0-9._-]+$`.
 
 ## Usage
 
+Hyperbrowser 1.0 accepts plain dictionaries for request parameters. Method
+signatures use `TypedDict` definitions, so editors can autocomplete keys at
+every nested level:
+
+```python
+from hyperbrowser import Hyperbrowser
+
+client = Hyperbrowser(api_key="test-key")
+
+# Preferred in 1.0: autocomplete works directly in the dictionary.
+session = client.sessions.create(
+    {
+        "use_stealth": True,
+        "screen": {"width": 1920, "height": 1080},
+    }
+)
+```
+
+Browser sessions can also use an outbound network policy. Omitting these fields
+keeps the default unrestricted behavior:
+
+```python
+session = client.sessions.create(
+    {
+        "allow_internet_access": False,
+        "allow_out": ["example.com"],
+        "deny_out": ["0.0.0.0/0"],
+    }
+)
+```
+
+Direct browser policies accept domains, IPv4 addresses, and CIDR ranges in
+`allow_out`; `deny_out` accepts IPv4 addresses and CIDR ranges. With a proxy,
+allow rules must be domains and the only supported deny rule is `0.0.0.0/0`.
+
+Existing Pydantic request classes remain accepted, so upgrading does not require
+an immediate rewrite:
+
+```python
+from hyperbrowser.models import CreateSessionParams, ScreenConfig
+
+session = client.sessions.create(
+    CreateSessionParams(
+        use_stealth=True,
+        screen=ScreenConfig(width=1920, height=1080),
+    )
+)
+```
+
+Import request annotations from `hyperbrowser.types` when a named variable is
+useful. The same names under `hyperbrowser.models` refer to the legacy Pydantic
+request classes. Responses remain Pydantic models.
+
+JSON Schema fields accept raw schema values, including object schemas with
+`$defs`, `$ref`, or custom keywords, and boolean schemas where the API supports
+them. Those schemas and other user-owned mappings are preserved as data; only
+SDK-owned request keys are translated to their API aliases. Schema fields
+documented as accepting a model class can also generate a schema from a Pydantic
+model.
+
+See the
+[Hyperbrowser Python SDK 1.0 migration guide](https://hyperbrowser.ai/docs/sdks/python-1-0-migration)
+for the complete compatibility details and migration checklist.
+
 ### Async
 
 ```python
 import asyncio
-from pyppeteer import connect
 from hyperbrowser import AsyncHyperbrowser
+from playwright.async_api import async_playwright
 
 HYPERBROWSER_API_KEY = "test-key"
 
@@ -43,29 +113,22 @@ async def main():
     async with AsyncHyperbrowser(api_key=HYPERBROWSER_API_KEY) as client:
         session = await client.sessions.create()
 
-        ws_endpoint = session.ws_endpoint
-        browser = await connect(browserWSEndpoint=ws_endpoint, defaultViewport=None)
-
-        # Get pages
-        pages = await browser.pages()
-        if not pages:
-            raise Exception("No pages available")
-
-        page = pages[0]
+        try:
+            async with async_playwright() as playwright:
+                browser = await playwright.chromium.connect_over_cdp(
+                    session.ws_endpoint
+                )
+                context = browser.contexts[0]
+                page = context.pages[0]
 
-        # Navigate to a website
-        print("Navigating to Hacker News...")
-        await page.goto("https://news.ycombinator.com/")
-        page_title = await page.title()
-        print("Page title:", page_title)
-
-        await page.close()
-        await browser.disconnect()
-        await client.sessions.stop(session.id)
-        print("Session completed!")
+                print("Navigating to Hacker News...")
+                await page.goto("https://news.ycombinator.com/")
+                print("Page title:", await page.title())
+        finally:
+            await client.sessions.stop(session.id)
 
 # Run the asyncio event loop
-asyncio.get_event_loop().run_until_complete(main())
+asyncio.run(main())
 ```
 ### Sync
 
@@ -115,17 +178,16 @@ The sync and async clients expose the same sandbox APIs through `client.sandboxe
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams
 
 client = Hyperbrowser(api_key="test-key")
 sandbox = client.sandboxes.create(
-    CreateSandboxParams(
-        image_name="node",
-        cpu=4,
-        memory_mib=4096,
-        disk_mib=8192,
-        exposed_ports=[SandboxExposeParams(port=3000, auth=True)],
-    )
+    {
+        "image_name": "node",
+        "cpu": 2,
+        "memory_mib": 2048,
+        "disk_mib": 8192,
+        "exposed_ports": [{"port": 3000, "auth": True}],
+    }
 )
 
 print(sandbox.exposed_ports[0].browser_url)
@@ -140,25 +202,24 @@ client.close()
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, CreateVolumeParams, SandboxVolumeMount
 
 client = Hyperbrowser(api_key="test-key")
 
-volume = client.volumes.create(CreateVolumeParams(name="project-cache"))
+volume = client.volumes.create({"name": "project-cache"})
 all_volumes = client.volumes.list()
 same_volume = client.volumes.get(volume.id)
 
 sandbox = client.sandboxes.create(
-    CreateSandboxParams(
-        image_name="node",
-        mounts={
-            "/workspace/cache": SandboxVolumeMount(
-                id=same_volume.id,
-                type="rw",
-                shared=True,
-            )
+    {
+        "image_name": "node",
+        "mounts": {
+            "/workspace/cache": {
+                "id": same_volume.id,
+                "type": "rw",
+                "shared": True,
+            }
         },
-    )
+    }
 )
 
 sandbox.stop()
@@ -169,17 +230,16 @@ client.close()
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import SandboxListParams
 
 client = Hyperbrowser(api_key="test-key")
 result = client.sandboxes.list(
-    SandboxListParams(
-        status="active",
-        search="sandbox",
-        start=1711929600000,
-        end=1712016000000,
-        limit=20,
-    )
+    {
+        "status": "active",
+        "search": "sandbox",
+        "start": 1711929600000,
+        "end": 1712016000000,
+        "limit": 20,
+    }
 )
 
 for sandbox in result.sandboxes:
@@ -190,11 +250,10 @@ for sandbox in result.sandboxes:
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import SandboxSnapshotListParams
 
 client = Hyperbrowser(api_key="test-key")
 snapshots = client.sandboxes.list_snapshots(
-    SandboxSnapshotListParams(image_name="node", status="created", limit=10)
+    {"image_name": "node", "status": "created", "limit": 10}
 )
 ```
 
@@ -202,16 +261,13 @@ snapshots = client.sandboxes.list_snapshots(
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams
 
 client = Hyperbrowser(api_key="test-key")
 sandbox = client.sandboxes.create(
-    CreateSandboxParams(
-        image_name="node", cpu=2, memory_mib=2048, disk_mib=8192
-    )
+    {"image_name": "node", "cpu": 2, "memory_mib": 2048, "disk_mib": 8192}
 )
 
-result = sandbox.expose(SandboxExposeParams(port=8080, auth=True))
+result = sandbox.expose({"port": 8080, "auth": True})
 print(result.url, result.browser_url)
 
 sandbox.unexpose(8080)
@@ -221,23 +277,19 @@ sandbox.unexpose(8080)
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, SandboxFileWriteEntry
 
 client = Hyperbrowser(api_key="test-key")
-sandbox = client.sandboxes.create(CreateSandboxParams(image_name="node"))
+sandbox = client.sandboxes.create({"image_name": "node"})
 
 sandbox.files.write(
     [
-        SandboxFileWriteEntry(
-            path="/tmp/config.json",
-            data='{"debug":true}\n',
-            append=True,
-            mode="600",
-        ),
-        SandboxFileWriteEntry(
-            path="/tmp/blob.bin",
-            data=b"\x00\x01\x02",
-        ),
+        {
+            "path": "/tmp/config.json",
+            "data": '{"debug":true}\n',
+            "append": True,
+            "mode": "600",
+        },
+        {"path": "/tmp/blob.bin", "data": b"\x00\x01\x02"},
     ]
 )
 ```
@@ -246,11 +298,10 @@ sandbox.files.write(
 
 ```python
 from hyperbrowser import Hyperbrowser
-from hyperbrowser.models import CreateSandboxParams, SandboxTerminalCreateParams
 
 client = Hyperbrowser(api_key="test-key")
-sandbox = client.sandboxes.create(CreateSandboxParams(image_name="node"))
-terminal = sandbox.terminal.create(SandboxTerminalCreateParams(command="bash"))
+sandbox = client.sandboxes.create({"image_name": "node"})
+terminal = sandbox.terminal.create({"command": "bash"})
 
 connection = terminal.attach(cursor=10)
 for event in connection.events():