ddp_utils.browser.facade.frames

import ddp_utils.browser.facade.frames

Backend-neutral frame navigation service.

class ddp_utils.browser.facade.frames.BrowserFrame(name: str, url: str, native: Any)

Bases: object

Describe one browser frame.

Parameters

Name	Type	Description
name	str	Provider-reported frame name when available.
url	str	Current frame URL when available.
native	Any	Provider-native frame object or Selenium target.

Examples

Inspect the frame selected for an operation:

frame = browser.frames.enter(0)
print(frame.url)

class ddp_utils.browser.facade.frames.BrowserFrames(browser: Browser)

Bases: object

Enter and leave frames through one synchronous contract.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Limit normal facade searches to one frame:

with browser.frames.use(frame_element):
    submit = browser.find("button", text="Submit", required=True)

Bind frame state to one browser session.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Browser creates this service once:

frames = BrowserFrames(browser)

property current: BrowserFrame

Return the active nested frame or None for the top document.

Returns

Active frame descriptor, or the main-frame descriptor.

Examples

Detect whether searches are frame-scoped:

if browser.frames.current is not None:
    browser.frames.reset()

all() → list[BrowserFrame]

Return all currently discoverable frames.

Returns

Type	Description
list[BrowserFrame]	Main frame followed by descendants.

Examples

frames = browser.frames.all().

property main: BrowserFrame

Return the main top-level frame.

Returns

Main frame descriptor.

Examples

browser.frames.switch(browser.frames.main).

find(*, name: str | None = None, url: str | None = None, selector: str | None = None) → BrowserFrame | None

Find a frame by name, URL glob, or iframe selector.

Parameters

Name	Type	Description
name	str | None	Optional exact frame name.
url	str | None	Optional URL glob.
selector	str | None	Optional iframe CSS selector.

Returns

Type	Description
BrowserFrame | None	Matching frame or None.

Examples

frame = browser.frames.find(name="results").

switch(frame: BrowserFrame | 'BrowserElement' | str | int) → BrowserFrame

Switch to a frame.

Parameters

Name	Type	Description
frame	BrowserFrame | 'BrowserElement' | str | int	Frame descriptor, element, name, URL, or index.

Returns

Type	Description
BrowserFrame	Active frame.

Examples

browser.frames.switch("results").

default() → BrowserFrame

Switch to the main document.

Returns

Type	Description
BrowserFrame	Main frame.

Examples

browser.frames.default().

parent() → BrowserFrame

Switch to the immediate parent frame.

Returns

Type	Description
BrowserFrame	Parent or main frame.

Examples

parent = browser.frames.parent().

within(frame: BrowserFrame | 'BrowserElement' | str | int) → Iterator[BrowserFrame]

Return a context manager scoped to one frame.

Parameters

Name	Type	Description
frame	BrowserFrame | 'BrowserElement' | str | int	Frame reference.

Returns

Type	Description
Iterator[BrowserFrame]	Context manager yielding the active frame.

Examples

with browser.frames.within("results"): ....

enter(target: BrowserElement | str | int) → BrowserFrame

Enter one child frame and make it the active facade search scope.

Parameters

Name	Type	Description
target	BrowserElement | str | int	Frame element, zero-based child-frame index, or frame name. Playwright also accepts an exact frame URL.

Returns

Type	Description
BrowserFrame	Active frame descriptor.

Raises

Exception	Description
BrowserError	The requested frame cannot be resolved.
UnsupportedCapabilityError	Frame navigation is unavailable.

Examples

Enter the first child frame:

browser.frames.enter(0)

exit() → BrowserFrame | None

Leave the current frame and return the new active parent.

Returns

Type	Description
BrowserFrame | None	Parent frame descriptor or None for the top document.

Raises

Exception	Description
BrowserError	No frame is currently active.
UnsupportedCapabilityError	Frame navigation is unavailable.

Examples

Return to the immediate parent frame:

parent = browser.frames.exit()

reset() → None

Return facade operations to the top-level document.

Raises

Exception	Description
UnsupportedCapabilityError	Frame navigation is unavailable.

Examples

Restore the top document after conditional frame work:

browser.frames.reset()

use(target: BrowserElement | str | int) → Iterator[BrowserFrame]

Enter a frame for one block and always restore its parent.

Parameters

Name	Type	Description
target	BrowserElement | str | int	Frame element, child index, name, or supported URL.

Yields

Active frame descriptor.

Raises

Exception	Description
BrowserError	The frame cannot be resolved.
UnsupportedCapabilityError	Frame navigation is unavailable.

Examples

Search within a frame without leaking frame state:

with browser.frames.use("results"):
    rows = browser.find_all("tr")