Skip to content

Commit aaaebd0

Browse files
kamathkamath
committed
following migration guide
1 parent d339f6e commit aaaebd0

File tree

1 file changed

+127
-50
lines changed

1 file changed

+127
-50
lines changed

‎migrating.md

+127-50
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,65 @@
1-
# Upgrade guide to v1.0
1+
# V1 Migration Guide
22

3-
The Browserbase v1.0.0 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. Unfortunately, however, this means that the old SDKs will be deprecated and archived in favor of the new SDK.
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.
44

55
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).
66

7+
## Major Changes
8+
9+
V1 SDK is a complete rewrite of the old SDK. The new SDK is more flexible, easier to use, and has a more consistent API. It is also a lot more modular. The majority of the syntax changes are as follows:
10+
11+
```python
12+
# Old SDK
13+
browserbase.list_sessions()
14+
15+
# New SDK
16+
bb.sessions.list()
17+
```
18+
19+
### Creating a Session
20+
21+
Similar to the above, the new way to create a session is to use the `create` method on the `sessions` object. However, the `CreateSessionOptions` object is now broken up into several params, saving you from having to import and instantiate a Pydantic object. For more on this, see [below](#create-session).
22+
23+
## Deprecated Methods
24+
25+
`load`, `load_url`, and `screenshot` are fully deprecated. You can use the following example instead that encapsulates the same functionality using Playwright.
26+
27+
```python
28+
from playwright.sync_api import Playwright, sync_playwright
29+
from browserbase import Browserbase
30+
31+
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
32+
33+
def run(playwright: Playwright) -> None:
34+
# Create a session on Browserbase
35+
session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID)
36+
37+
# Connect to the remote session
38+
chromium = playwright.chromium
39+
browser = chromium.connect_over_cdp(session.connect_url)
40+
context = browser.contexts[0]
41+
page = context.pages[0]
42+
43+
# Execute Playwright actions on the remote browser tab
44+
page.goto("https://news.ycombinator.com/")
45+
page_title = page.title()
46+
assert (
47+
page_title == "Hacker News"
48+
), f"Page title is not 'Hacker News', it is '{page_title}'"
49+
page.screenshot(path="screenshot.png")
50+
51+
page.close()
52+
browser.close()
53+
print("Done!")
54+
55+
56+
if __name__ == "__main__":
57+
with sync_playwright() as playwright:
58+
run(playwright)
59+
```
60+
61+
For async Playwright, you can import `async_playwright` instead.
62+
763
## Create Session
864

965
### Old SDK
@@ -45,7 +101,7 @@ session = bb.sessions.create(
45101
)
46102
```
47103

48-
## Get Connection Url
104+
## Get Connect Url
49105

50106
### Old SDK
51107

@@ -67,9 +123,20 @@ connect_url = browserbase.get_connect_url(session_id=some_session.id)
67123
from browserbase import Browserbase
68124
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
69125

70-
# We must create a session first
71-
session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID)
72-
connect_url = session.connect_url
126+
def get_connect_url(bb: Browserbase, session_id: str = None):
127+
"""
128+
Retrieve a connect url for a given session or create a new one.
129+
130+
If a session id is provided, retrieve the connect url for the existing session.
131+
Otherwise, create a new session and return the connect url.
132+
"""
133+
if session_id:
134+
session = bb.sessions.retrieve(id=session_id)
135+
else:
136+
session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID)
137+
return session.connect_url
138+
139+
connect_url = get_connect_url(bb, session_id="some_session_id")
73140
```
74141

75142
## List Sessions
@@ -87,7 +154,14 @@ sessions = browserbase.list_sessions()
87154
```python
88155
from browserbase import Browserbase
89156
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
90-
sessions = bb.sessions.list()
157+
158+
def list_sessions(bb: Browserbase):
159+
"""
160+
List all sessions for the given project.
161+
"""
162+
return bb.sessions.list()
163+
164+
sessions = list_sessions(bb)
91165
```
92166

93167
## Complete Session
@@ -106,7 +180,14 @@ browserbase.complete_session(session_id=some_session.id)
106180
```python
107181
from browserbase import Browserbase
108182
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
109-
bb.sessions.update(id=some_session.id, status="REQUEST_RELEASE")
183+
184+
def complete_session(bb: Browserbase, session_id: str):
185+
"""
186+
Complete a session by updating its status to REQUEST_RELEASE.
187+
"""
188+
bb.sessions.update(id=session_id, status="REQUEST_RELEASE")
189+
190+
complete_session(bb, session_id="some_session_id")
110191
```
111192

112193
## Get Session
@@ -116,15 +197,22 @@ bb.sessions.update(id=some_session.id, status="REQUEST_RELEASE")
116197
```python
117198
from browserbase import Browserbase
118199
browserbase = Browserbase(api_key=BROWSERBASE_API_KEY, project_id=BROWSERBASE_PROJECT_ID)
119-
session = browserbase.get_session(session_id=some_session.id)
200+
session = browserbase.get_session(session_id="some_session_id")
120201
```
121202

122203
### New SDK
123204

124205
```python
125206
from browserbase import Browserbase
126207
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
127-
session = bb.sessions.retrieve(id=some_session.id)
208+
209+
def get_session(bb: Browserbase, session_id: str):
210+
"""
211+
Retrieve a session by id.
212+
"""
213+
return bb.sessions.retrieve(id=session_id)
214+
215+
session = get_session(bb, session_id="some_session_id")
128216
```
129217

130218
## Get Session Recording
@@ -142,7 +230,13 @@ recording = browserbase.get_session_recording(session_id=some_session.id)
142230
```python
143231
from browserbase import Browserbase
144232
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
145-
recording = bb.sessions.recording.retrieve(id=some_session.id)
233+
def get_session_recording(bb: Browserbase, session_id: str):
234+
"""
235+
Retrieve a session recording by id.
236+
"""
237+
return bb.sessions.recording.retrieve(id=session_id)
238+
239+
recording = get_session_recording(bb, session_id="some_session_id")
146240
```
147241

148242
## Get Session Downloads
@@ -165,7 +259,14 @@ downloads = browserbase.get_session_downloads(session_id=some_session.id)
165259
```python
166260
from browserbase import Browserbase
167261
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
168-
downloads = bb.sessions.downloads.list(id=some_session.id)
262+
263+
def get_session_downloads(bb: Browserbase, session_id: str):
264+
"""
265+
Retrieve a session's downloads by id.
266+
"""
267+
return bb.sessions.downloads.list(id=session_id)
268+
269+
downloads = get_session_downloads(bb, session_id="some_session_id")
169270
```
170271

171272
## Get Debug Connection URLs
@@ -183,7 +284,14 @@ debug_urls = browserbase.get_debug_connection_urls(session_id=some_session.id)
183284
```python
184285
from browserbase import Browserbase
185286
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
186-
debug_urls = bb.sessions.debug(id=some_session.id)
287+
288+
def get_debug_connection_urls(bb: Browserbase, session_id: str):
289+
"""
290+
Retrieve a session's debug connection urls by id.
291+
"""
292+
return bb.sessions.debug(id=session_id)
293+
294+
debug_urls = get_debug_connection_urls(bb, session_id="some_session_id")
187295
```
188296

189297
## Get Session Logs
@@ -201,43 +309,12 @@ logs = browserbase.get_session_logs(session_id=some_session.id)
201309
```python
202310
from browserbase import Browserbase
203311
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
204-
logs = bb.sessions.logs.list(id=some_session.id)
205-
```
206-
207-
# Deprecated Methods
208-
209-
`load`, `load_url`, and `screenshot` are fully deprecated. You can use the following example instead that encapsulates the same functionality using Playwright
210-
211-
```python
212-
from playwright.sync_api import Playwright, sync_playwright
213-
from browserbase import Browserbase
214-
215-
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
216-
217-
def run(playwright: Playwright) -> None:
218-
# Create a session on Browserbase
219-
session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID)
220312

221-
# Connect to the remote session
222-
chromium = playwright.chromium
223-
browser = chromium.connect_over_cdp(session.connect_url)
224-
context = browser.contexts[0]
225-
page = context.pages[0]
313+
def get_session_logs(bb: Browserbase, session_id: str):
314+
"""
315+
Retrieve a session's logs by id.
316+
"""
317+
return bb.sessions.logs.list(id=session_id)
226318

227-
# Execute Playwright actions on the remote browser tab
228-
page.goto("https://news.ycombinator.com/")
229-
page_title = page.title()
230-
assert (
231-
page_title == "Hacker News"
232-
), f"Page title is not 'Hacker News', it is '{page_title}'"
233-
page.screenshot(path="screenshot.png")
234-
235-
page.close()
236-
browser.close()
237-
print("Done!")
238-
239-
240-
if __name__ == "__main__":
241-
with sync_playwright() as playwright:
242-
run(playwright)
319+
logs = get_session_logs(bb, session_id="some_session_id")
243320
```

0 commit comments

Comments
 (0)