diff --git a/.release-please-manifest.json b/.release-please-manifest.json index fea34540..2601677b 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "1.0.0" + ".": "1.1.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 1a6b2b54..b04bed28 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 18 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fbrowserbase-b341dd9d5bb77c4f217b94b186763e730fd798fbb773a5e90bb4e2a8d4a2c822.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fbrowserbase-d8e42f141c0955e8100ca3ce041ce8dedf5dcf68b04e554a5704e4c2003c2fd4.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index a17bbc56..1ff2dcea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## 1.1.0 (2024-11-01) + +Full Changelog: [v1.0.0...v1.1.0](https://github.com/browserbase/sdk-python/compare/v1.0.0...v1.1.0) + +### Features + +* **api:** api update ([#48](https://github.com/browserbase/sdk-python/issues/48)) ([645e897](https://github.com/browserbase/sdk-python/commit/645e897348d54bef40cb2d9470838da6617cfb34)) +* comment ([c04f506](https://github.com/browserbase/sdk-python/commit/c04f506802c8b4995883433e41e52b6f6a3cc4e6)) +* following migration guide ([6389dcf](https://github.com/browserbase/sdk-python/commit/6389dcfa255f2dbccba21e213697f45130985f29)) +* migrating docs ([f5c9093](https://github.com/browserbase/sdk-python/commit/f5c90937330f2acfe4c6a97983136f3f482c7d39)) +* migration guide final ([0992323](https://github.com/browserbase/sdk-python/commit/09923239bf5206adc9d119f89bad9608681a5d30)) +* rm scratch ([bc333a4](https://github.com/browserbase/sdk-python/commit/bc333a4d9ab906e73bfbdd145bb6698ce9842318)) +* syntax ([27c1113](https://github.com/browserbase/sdk-python/commit/27c1113c47fdca5306d3d87c924d24ab66e8ab78)) +* undo playwright_roxy ([2530a9c](https://github.com/browserbase/sdk-python/commit/2530a9c6aa9c8aa29b180a7a5a912251dca4b2d9)) +* uppacase ([9ffd582](https://github.com/browserbase/sdk-python/commit/9ffd582fa4b869dbfdd91154eb17c0cbe7aa7120)) + ## 1.0.0 (2024-10-29) Full Changelog: [v1.0.0-alpha.0...v1.0.0](https://github.com/browserbase/sdk-python/compare/v1.0.0-alpha.0...v1.0.0) diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 00000000..4b492059 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,241 @@ +# Migration Guide + +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. + +We hope this guide is useful to you; if you have any questions don't hesitate to reach out to support@browserbase.com or [create a new issue](https://github.com/browserbase/sdk-python/issues/new). + +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. + +## Breaking Changes + +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: + +```python +# v0 SDK +browserbase.list_sessions() + +# v1 SDK +bb.sessions.list() +``` + +### Deleted Methods + +`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. + +```python +from playwright.sync_api import Playwright, sync_playwright +from browserbase import Browserbase + +bb = Browserbase(api_key=BROWSERBASE_API_KEY) + +def run(playwright: Playwright) -> None: + # Create a session on Browserbase + session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID) + + # Connect to the remote session + chromium = playwright.chromium + browser = chromium.connect_over_cdp(session.connect_url) + context = browser.contexts[0] + page = context.pages[0] + + # Execute Playwright actions on the remote browser tab + page.goto("https://news.ycombinator.com/") + page_title = page.title() + assert ( + page_title == "Hacker News" + ), f"Page title is not 'Hacker News', it is '{page_title}'" + page.screenshot(path="screenshot.png") + + page.close() + browser.close() + print(f"Done! View replay at https://browserbase.com/sessions/{session.id}") + + +if __name__ == "__main__": + with sync_playwright() as playwright: + run(playwright) +``` + +For async Playwright (like in Jupyter notebooks or IPython environments), you can import `async_playwright` instead of `sync_playwright`. + +## Updates to Common Workflows + +### Create Session + +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). + +```python +# v0 SDK +from browserbase import Browserbase, CreateSessionOptions + +browserbase = Browserbase(api_key=BROWSERBASE_API_KEY, project_id=BROWSERBASE_PROJECT_ID) +options = CreateSessionOptions(extensionId='123') +browserbase.create_session(options) +``` + +Now, you can create a session with the v1 SDK by calling the `create` method on `sessions`. + +```python +# v1 SDK +from browserbase import Browserbase + +bb = Browserbase(api_key=BROWSERBASE_API_KEY) +session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID, extension_id="some_extension_id") +``` + +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. + +```python +# v1 SDK +from browserbase import Browserbase +from pydantic import TypeAdapter +from browserbase.types.session_create_params import BrowserSettings + +session = bb.sessions.create( + project_id=BROWSERBASE_PROJECT_ID, + extension_id="some_extension_id", + browser_settings=TypeAdapter(BrowserSettings).validate_python( + {"context": {"id": context_id, "persist": True}} + ), + ) +``` + +### Get Connect URL + +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. + +In the v1 SDK, you can create a session and retrieve its connect url in a single call with `bb.sessions.create()`. + +```python +# v0 SDK +from browserbase import Browserbase + +browserbase = Browserbase(api_key=BROWSERBASE_API_KEY, project_id=BROWSERBASE_PROJECT_ID) + +# To create a new session and connect to it +connect_url = browserbase.get_connect_url() + +# To connect to an existing session +connect_url = browserbase.get_connect_url(session_id=some_session.id) +``` + +```python +# v1 SDK +from browserbase import Browserbase +bb = Browserbase(api_key=BROWSERBASE_API_KEY) + +def get_connect_url(bb: Browserbase, session_id: str = None): + """ + Retrieve a connect url for a given session or create a new one. + + If a session id is provided, retrieve the connect url for the existing session. + Otherwise, create a new session and return the connect url. + """ + if session_id: + session = bb.sessions.retrieve(id=session_id) + else: + session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID) + return session.connect_url + +connect_url = get_connect_url(bb, session_id="some_session_id") +``` + +### Complete Session + +v0 allowed you to complete a session by calling `browserbase.complete_session(session_id=some_session.id)`. + +```python +# v0 SDK +browserbase.complete_session(session_id=some_session.id) +``` + +In the v1 SDK, completing a session is done by updating its status to `REQUEST_RELEASE`. + +```python +# v1 SDK +bb.sessions.update(id=session_id, status="REQUEST_RELEASE") +``` + +## Reference for other methods + +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()`. + +### List Sessions + +```python +# v0 SDK +sessions = browserbase.list_sessions() +``` + +```python +# v1 SDK +sessions = bb.sessions.list() +``` + +### Get Session + +```python +# v0 SDK +session = browserbase.get_session(session_id="some_session_id") +``` + +```python +# v1 SDK +session = bb.sessions.retrieve(id="some_session_id") +``` + +### Get Session Recording + +```python +# v0 SDK +recording = browserbase.get_session_recording(session_id=some_session.id) +``` + +```python +# v1 SDK +recording = bb.sessions.recording.retrieve(id="some_session_id") +``` + +### Get Session Downloads + +**Note:** The parameter `retry_interval` is no longer supported. You can configure retries with the following syntax on bb init: + +```python +bb = Browserbase(api_key=BROWSERBASE_API_KEY, max_retries=5) +``` + +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: + +```python +# v0 SDK +downloads = browserbase.get_session_downloads(session_id=some_session.id) +``` + +```python +# v1 SDK +downloads = bb.sessions.downloads.retrieve(id="some_session_id") +``` + +### Get Debug Connection URLs + +```python +# v0 SDK +debug_urls = browserbase.get_debug_connection_urls(session_id=some_session.id) +``` + +```python +# v1 SDK +debug_urls = bb.sessions.debug.list(id="some_session_id") +``` + +### Get Session Logs + +```python +# v0 SDK +logs = browserbase.get_session_logs(session_id=some_session.id) +``` + +```python +# v1 SDK +logs = bb.sessions.logs.list(id="some_session_id") +``` diff --git a/pyproject.toml b/pyproject.toml index 9cdf351a..ec42980d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "browserbase" -version = "1.0.0" +version = "1.1.0" description = "The official Python library for the Browserbase API" dynamic = ["readme"] license = "Apache-2.0" diff --git a/src/browserbase/_version.py b/src/browserbase/_version.py index 1f27c648..9621169e 100644 --- a/src/browserbase/_version.py +++ b/src/browserbase/_version.py @@ -1,4 +1,4 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. __title__ = "browserbase" -__version__ = "1.0.0" # x-release-please-version +__version__ = "1.1.0" # x-release-please-version diff --git a/src/browserbase/resources/projects.py b/src/browserbase/resources/projects.py index f8b1936a..bf4a5df9 100644 --- a/src/browserbase/resources/projects.py +++ b/src/browserbase/resources/projects.py @@ -84,7 +84,7 @@ def list( extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN, ) -> ProjectListResponse: - """List all projects""" + """List projects""" return self._get( "/v1/projects", options=make_request_options( @@ -190,7 +190,7 @@ async def list( extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN, ) -> ProjectListResponse: - """List all projects""" + """List projects""" return await self._get( "/v1/projects", options=make_request_options(