Skip to content

Commit 41e394b

Browse files
authored
docs: allow overriding return types (#5031)
1 parent 940cf35 commit 41e394b

13 files changed

+159
-229
lines changed

docs/src/api/class-browsercontext.md

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -567,7 +567,7 @@ await browser.close();
567567
```python async
568568
context = await browser.new_context()
569569
page = await context.new_page()
570-
await context.route(r"(\.png$)|(\.jpg$)", lambda route: route.abort())
570+
await context.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
571571
page = await context.new_page()
572572
await page.goto("https://example.com")
573573
await browser.close()
@@ -576,7 +576,7 @@ await browser.close()
576576
```python sync
577577
context = browser.new_context()
578578
page = context.new_page()
579-
context.route(r"(\.png$)|(\.jpg$)", lambda route: route.abort())
579+
context.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
580580
page = await context.new_page()
581581
page = context.new_page()
582582
page.goto("https://example.com")
@@ -736,24 +736,30 @@ A glob pattern, regex pattern or predicate receiving [URL] used to register a ro
736736
Optional handler function used to register a routing with [`method: BrowserContext.route`].
737737

738738
## async method: BrowserContext.waitForEvent
739+
* langs:
740+
- alias-python: expect_event
739741
- returns: <[any]>
740742

741743
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy
742744
value. Will throw an error if the context closes before the event is fired. Returns the event data value.
743745

744746
```js
745-
const context = await browser.newContext();
746-
await context.grantPermissions(['geolocation']);
747+
const [page, _] = await Promise.all([
748+
context.waitForEvent('page'),
749+
page.click('button')
750+
]);
747751
```
748752

749753
```python async
750-
context = await browser.new_context()
751-
await context.grant_permissions(["geolocation"])
754+
async with context.expect_event("page") as event_info:
755+
await page.click("button")
756+
page = await event_info.value
752757
```
753758

754759
```python sync
755-
context = browser.new_context()
756-
context.grant_permissions(["geolocation"])
760+
with context.expect_event("page") as event_info:
761+
page.click("button")
762+
page = event_info.value
757763
```
758764

759765
### param: BrowserContext.waitForEvent.event

docs/src/api/class-frame.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1135,11 +1135,13 @@ frame.wait_for_load_state() # the promise resolves after "load" event.
11351135
### option: Frame.waitForLoadState.timeout = %%-navigation-timeout-%%
11361136

11371137
## async method: Frame.waitForNavigation
1138+
* langs:
1139+
* alias-python: expect_navigation
11381140
- returns: <[null]|[Response]>
11391141

1140-
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
1141-
last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will
1142-
resolve with `null`.
1142+
Waits for the frame navigation and returns the main resource response. In case of multiple redirects, the navigation
1143+
will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to
1144+
History API usage, the navigation will resolve with `null`.
11431145

11441146
This method waits for the frame to navigate to a new URL. It is useful for when you run code which will indirectly cause
11451147
the frame to navigate. Consider this example:

docs/src/api/class-page.md

Lines changed: 47 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1783,14 +1783,14 @@ await browser.close();
17831783

17841784
```python async
17851785
page = await browser.new_page()
1786-
await page.route(r"(\.png$)|(\.jpg$)", lambda route: route.abort())
1786+
await page.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
17871787
await page.goto("https://example.com")
17881788
await browser.close()
17891789
```
17901790

17911791
```python sync
17921792
page = browser.new_page()
1793-
page.route(r"(\.png$)|(\.jpg$)", lambda route: route.abort())
1793+
page.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
17941794
page.goto("https://example.com")
17951795
browser.close()
17961796
```
@@ -2163,12 +2163,31 @@ Video object associated with this page.
21632163
- `height` <[int]> page height in pixels.
21642164

21652165
## async method: Page.waitForEvent
2166+
* langs:
2167+
- alias-python: expect_event
21662168
- returns: <[any]>
21672169

2168-
Returns the event data value.
2169-
21702170
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy
2171-
value. Will throw an error if the page is closed before the event is fired.
2171+
value. Will throw an error if the page is closed before the event is fired. Returns the event data value.
2172+
2173+
```js
2174+
const [frame, _] = await Promise.all([
2175+
page.waitForEvent('framenavigated'),
2176+
page.click('button')
2177+
]);
2178+
```
2179+
2180+
```python async
2181+
async with page.expect_event("framenavigated") as event_info:
2182+
await page.click("button")
2183+
frame = await event_info.value
2184+
```
2185+
2186+
```python sync
2187+
with page.expect_event("framenavigated") as event_info:
2188+
page.click("button")
2189+
frame = event_info.value
2190+
```
21722191

21732192
### param: Page.waitForEvent.event = %%-wait-for-event-event-%%
21742193

@@ -2329,11 +2348,13 @@ Shortcut for main frame's [`method: Frame.waitForLoadState`].
23292348
### option: Page.waitForLoadState.timeout = %%-navigation-timeout-%%
23302349

23312350
## async method: Page.waitForNavigation
2351+
* langs:
2352+
* alias-python: expect_navigation
23322353
- returns: <[null]|[Response]>
23332354

2334-
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
2335-
last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will
2336-
resolve with `null`.
2355+
Waits for the main frame navigation and returns the main resource response. In case of multiple redirects, the navigation
2356+
will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to
2357+
History API usage, the navigation will resolve with `null`.
23372358

23382359
This resolves when the page navigates to a new URL or reloads. It is useful for when you run code which will indirectly
23392360
cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`.
@@ -2372,6 +2393,8 @@ Shortcut for main frame's [`method: Frame.waitForNavigation`].
23722393
### option: Page.waitForNavigation.waitUntil = %%-navigation-wait-until-%%
23732394

23742395
## async method: Page.waitForRequest
2396+
* langs:
2397+
* alias-python: expect_request
23752398
- returns: <[Request]>
23762399

23772400
Waits for the matching request and returns it.
@@ -2383,15 +2406,23 @@ return firstRequest.url();
23832406
```
23842407

23852408
```python async
2386-
first_request = await page.wait_for_request("http://example.com/resource")
2387-
final_request = await page.wait_for_request(lambda request: request.url == "http://example.com" and request.method == "get")
2388-
return first_request.url
2409+
async with page.expect_request("http://example.com/resource") as first:
2410+
await page.click('button')
2411+
first_request = await first.value
2412+
2413+
async with page.expect_request(lambda request: request.url == "http://example.com" and request.method == "get") as second:
2414+
await page.click('img')
2415+
second_request = await second.value
23892416
```
23902417

23912418
```python sync
2392-
first_request = page.wait_for_request("http://example.com/resource")
2393-
final_request = page.wait_for_request(lambda request: request.url == "http://example.com" and request.method == "get")
2394-
return first_request.url
2419+
with page.expect_request("http://example.com/resource") as first:
2420+
page.click('button')
2421+
first_request = first.value
2422+
2423+
with page.expect_request(lambda request: request.url == "http://example.com" and request.method == "get") as second:
2424+
page.click('img')
2425+
second_request = second.value
23952426
```
23962427

23972428
```js
@@ -2410,6 +2441,8 @@ Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable t
24102441
changed by using the [`method: Page.setDefaultTimeout`] method.
24112442

24122443
## async method: Page.waitForResponse
2444+
* langs:
2445+
* alias-python: expect_response
24132446
- returns: <[Response]>
24142447

24152448
Returns the matched response.

docs/src/api/class-request.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ If request gets a 'redirect' response, the request is successfully finished with
1717
request is issued to a redirected url.
1818

1919
## method: Request.failure
20-
* langs: js
2120
- returns: <[null]|[Object]>
2221
- `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.
2322

docs/src/api/class-response.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@
88
Returns the buffer with response body.
99

1010
## async method: Response.finished
11-
* langs: js
1211
- returns: <[null]|[Error]>
1312

1413
Waits for this response to finish, returns failure error if request failed.

docs/src/api/class-websocket.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,12 @@ Indicates that the web socket has been closed.
3434
Contains the URL of the WebSocket.
3535

3636
## async method: WebSocket.waitForEvent
37+
* langs:
38+
- alias-python: expect_event
3739
- returns: <[any]>
3840

39-
Returns the event data value.
40-
4141
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy
42-
value. Will throw an error if the webSocket is closed before the event is fired.
42+
value. Will throw an error if the webSocket is closed before the event is fired. Returns the event data value.
4343

4444
### param: WebSocket.waitForEvent.event
4545
- `event` <[string]>

0 commit comments

Comments
 (0)