|
| 1 | +# Migration Guide |
| 2 | + |
| 3 | +The Browserbase v1 Python SDK has been rewritten from the ground up and ships with a ton of new features and better support that we can't wait for you to try. This guide is designed to help you maximize your experience with v1. |
| 4 | + |
| 5 | +We hope this guide is useful to you; if you have any questions don't hesitate to reach out to [email protected] or [create a new issue ](https://github.com/browserbase/sdk-python/issues/new). |
| 6 | + |
| 7 | +We've written out specific guidelines on how to migrate each v0 method to v1 below. v1 also adds one-to-one mappings for every API endpoint, so you can incorporate new Browserbase features in your codebase with much less lift. |
| 8 | + |
| 9 | +## Breaking Changes |
| 10 | + |
| 11 | +The v1 SDK is more flexible, easier to use, and has a more consistent API. It is also a lot more modular, meaning the majority of function calls have changed from `browserbase.$thing_$do()` to `browserbase.$thing.$do()`. For example: |
| 12 | + |
| 13 | +```python |
| 14 | +# v0 SDK |
| 15 | +browserbase.list_sessions() |
| 16 | + |
| 17 | +# v1 SDK |
| 18 | +bb.sessions.list() |
| 19 | +``` |
| 20 | + |
| 21 | +### Deleted Methods |
| 22 | + |
| 23 | +`load`, `load_url`, and `screenshot` have been fully removed in the v1 SDK. You can use the following example instead that encapsulates the same functionality using Playwright. |
| 24 | + |
| 25 | +```python |
| 26 | +from playwright.sync_api import Playwright, sync_playwright |
| 27 | +from browserbase import Browserbase |
| 28 | + |
| 29 | +bb = Browserbase(api_key=BROWSERBASE_API_KEY) |
| 30 | + |
| 31 | +def run(playwright: Playwright) -> None: |
| 32 | + # Create a session on Browserbase |
| 33 | + session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID) |
| 34 | + |
| 35 | + # Connect to the remote session |
| 36 | + chromium = playwright.chromium |
| 37 | + browser = chromium.connect_over_cdp(session.connect_url) |
| 38 | + context = browser.contexts[0] |
| 39 | + page = context.pages[0] |
| 40 | + |
| 41 | + # Execute Playwright actions on the remote browser tab |
| 42 | + page.goto("https://news.ycombinator.com/") |
| 43 | + page_title = page.title() |
| 44 | + assert ( |
| 45 | + page_title == "Hacker News" |
| 46 | + ), f"Page title is not 'Hacker News', it is '{page_title}'" |
| 47 | + page.screenshot(path="screenshot.png") |
| 48 | + |
| 49 | + page.close() |
| 50 | + browser.close() |
| 51 | + print(f"Done! View replay at https://browserbase.com/sessions/{session.id}") |
| 52 | + |
| 53 | + |
| 54 | +if __name__ == "__main__": |
| 55 | + with sync_playwright() as playwright: |
| 56 | + run(playwright) |
| 57 | +``` |
| 58 | + |
| 59 | +For async Playwright (like in Jupyter notebooks or IPython environments), you can import `async_playwright` instead of `sync_playwright`. |
| 60 | + |
| 61 | +## Updates to Common Workflows |
| 62 | + |
| 63 | +### Create Session |
| 64 | + |
| 65 | +This is how you would create a session with the v0 SDK, where `CreateSessionOptions` is a Pydantic object defined [here](https://github.com/browserbase/python-sdk/blob/0a499ba29853f20bb3055d7c81c5f61c24fcd9ec/browserbase/__init__.py#L52). |
| 66 | + |
| 67 | +```python |
| 68 | +# v0 SDK |
| 69 | +from browserbase import Browserbase, CreateSessionOptions |
| 70 | + |
| 71 | +browserbase = Browserbase(api_key=BROWSERBASE_API_KEY, project_id=BROWSERBASE_PROJECT_ID) |
| 72 | +options = CreateSessionOptions(extensionId='123') |
| 73 | +browserbase.create_session(options) |
| 74 | +``` |
| 75 | + |
| 76 | +Now, you can create a session with the v1 SDK by calling the `create` method on `sessions`. |
| 77 | + |
| 78 | +```python |
| 79 | +# v1 SDK |
| 80 | +from browserbase import Browserbase |
| 81 | + |
| 82 | +bb = Browserbase(api_key=BROWSERBASE_API_KEY) |
| 83 | +session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID, extension_id="some_extension_id") |
| 84 | +``` |
| 85 | + |
| 86 | +For more complex session creation, you can import `BrowserSettings` and use Pydantic's `TypeAdapter` to conform JSON spec to the appropriate Pydantic class. You can also import each individual subclass. |
| 87 | + |
| 88 | +```python |
| 89 | +# v1 SDK |
| 90 | +from browserbase import Browserbase |
| 91 | +from pydantic import TypeAdapter |
| 92 | +from browserbase.types.session_create_params import BrowserSettings |
| 93 | + |
| 94 | +session = bb.sessions.create( |
| 95 | + project_id=BROWSERBASE_PROJECT_ID, |
| 96 | + extension_id="some_extension_id", |
| 97 | + browser_settings=TypeAdapter(BrowserSettings).validate_python( |
| 98 | + {"context": {"id": context_id, "persist": True}} |
| 99 | + ), |
| 100 | + ) |
| 101 | +``` |
| 102 | + |
| 103 | +### Get Connect URL |
| 104 | + |
| 105 | +In the v0 SDK, you could run `browserbase.get_connect_url()` to create a new session and retrieve its connect url, or `browserbase.get_connect_url(session_id=some_session.id)` to retrieve the connect url for an existing session. |
| 106 | + |
| 107 | +In the v1 SDK, you can create a session and retrieve its connect url in a single call with `bb.sessions.create()`. |
| 108 | + |
| 109 | +```python |
| 110 | +# v0 SDK |
| 111 | +from browserbase import Browserbase |
| 112 | + |
| 113 | +browserbase = Browserbase(api_key=BROWSERBASE_API_KEY, project_id=BROWSERBASE_PROJECT_ID) |
| 114 | + |
| 115 | +# To create a new session and connect to it |
| 116 | +connect_url = browserbase.get_connect_url() |
| 117 | + |
| 118 | +# To connect to an existing session |
| 119 | +connect_url = browserbase.get_connect_url(session_id=some_session.id) |
| 120 | +``` |
| 121 | + |
| 122 | +```python |
| 123 | +# v1 SDK |
| 124 | +from browserbase import Browserbase |
| 125 | +bb = Browserbase(api_key=BROWSERBASE_API_KEY) |
| 126 | + |
| 127 | +def get_connect_url(bb: Browserbase, session_id: str = None): |
| 128 | + """ |
| 129 | + Retrieve a connect url for a given session or create a new one. |
| 130 | +
|
| 131 | + If a session id is provided, retrieve the connect url for the existing session. |
| 132 | + Otherwise, create a new session and return the connect url. |
| 133 | + """ |
| 134 | + if session_id: |
| 135 | + session = bb.sessions.retrieve(id=session_id) |
| 136 | + else: |
| 137 | + session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID) |
| 138 | + return session.connect_url |
| 139 | + |
| 140 | +connect_url = get_connect_url(bb, session_id="some_session_id") |
| 141 | +``` |
| 142 | + |
| 143 | +### Complete Session |
| 144 | + |
| 145 | +v0 allowed you to complete a session by calling `browserbase.complete_session(session_id=some_session.id)`. |
| 146 | + |
| 147 | +```python |
| 148 | +# v0 SDK |
| 149 | +browserbase.complete_session(session_id=some_session.id) |
| 150 | +``` |
| 151 | + |
| 152 | +In the v1 SDK, completing a session is done by updating its status to `REQUEST_RELEASE`. |
| 153 | + |
| 154 | +```python |
| 155 | +# v1 SDK |
| 156 | +bb.sessions.update(id=session_id, status="REQUEST_RELEASE") |
| 157 | +``` |
| 158 | + |
| 159 | +## Reference for other methods |
| 160 | + |
| 161 | +These methods have been rewritten for modularity and flexibility. As mentioned above, the pattern here is that the method has been renamed from `browserbase.$thing_$do()` to `bb.$thing.$do()`. |
| 162 | + |
| 163 | +### List Sessions |
| 164 | + |
| 165 | +```python |
| 166 | +# v0 SDK |
| 167 | +sessions = browserbase.list_sessions() |
| 168 | +``` |
| 169 | + |
| 170 | +```python |
| 171 | +# v1 SDK |
| 172 | +sessions = bb.sessions.list() |
| 173 | +``` |
| 174 | + |
| 175 | +### Get Session |
| 176 | + |
| 177 | +```python |
| 178 | +# v0 SDK |
| 179 | +session = browserbase.get_session(session_id="some_session_id") |
| 180 | +``` |
| 181 | + |
| 182 | +```python |
| 183 | +# v1 SDK |
| 184 | +session = bb.sessions.retrieve(id="some_session_id") |
| 185 | +``` |
| 186 | + |
| 187 | +### Get Session Recording |
| 188 | + |
| 189 | +```python |
| 190 | +# v0 SDK |
| 191 | +recording = browserbase.get_session_recording(session_id=some_session.id) |
| 192 | +``` |
| 193 | + |
| 194 | +```python |
| 195 | +# v1 SDK |
| 196 | +recording = bb.sessions.recording.retrieve(id="some_session_id") |
| 197 | +``` |
| 198 | + |
| 199 | +### Get Session Downloads |
| 200 | + |
| 201 | +**Note:** The parameter `retry_interval` is no longer supported. You can configure retries with the following syntax on bb init: |
| 202 | + |
| 203 | +```python |
| 204 | +bb = Browserbase(api_key=BROWSERBASE_API_KEY, max_retries=5) |
| 205 | +``` |
| 206 | + |
| 207 | +Keep in mind, however, that this only affects the default retry behavior, which will only retry on 4xx/5xx errors. The remaining pattern still applies: |
| 208 | + |
| 209 | +```python |
| 210 | +# v0 SDK |
| 211 | +downloads = browserbase.get_session_downloads(session_id=some_session.id) |
| 212 | +``` |
| 213 | + |
| 214 | +```python |
| 215 | +# v1 SDK |
| 216 | +downloads = bb.sessions.downloads.retrieve(id="some_session_id") |
| 217 | +``` |
| 218 | + |
| 219 | +### Get Debug Connection URLs |
| 220 | + |
| 221 | +```python |
| 222 | +# v0 SDK |
| 223 | +debug_urls = browserbase.get_debug_connection_urls(session_id=some_session.id) |
| 224 | +``` |
| 225 | + |
| 226 | +```python |
| 227 | +# v1 SDK |
| 228 | +debug_urls = bb.sessions.debug.list(id="some_session_id") |
| 229 | +``` |
| 230 | + |
| 231 | +### Get Session Logs |
| 232 | + |
| 233 | +```python |
| 234 | +# v0 SDK |
| 235 | +logs = browserbase.get_session_logs(session_id=some_session.id) |
| 236 | +``` |
| 237 | + |
| 238 | +```python |
| 239 | +# v1 SDK |
| 240 | +logs = bb.sessions.logs.list(id="some_session_id") |
| 241 | +``` |
0 commit comments