ddp_utils.browser.facade.pages

import ddp_utils.browser.facade.pages

Backend-neutral browser page and window service.

class ddp_utils.browser.facade.pages.BrowserPage(identifier: str, url: str, title: str, native: Any)

Bases: object

Describe one top-level browser page or WebDriver window.

Parameters

Name	Type	Description
identifier	str	Stable process-local facade identifier.
url	str	Observed page URL.
title	str	Observed page title.
native	Any	Native page object or Selenium window handle.

Examples

Select a page by URL without backend branching:

page = next(item for item in browser.pages.all() if "/results" in item.url)

class ddp_utils.browser.facade.pages.BrowserPages(browser: Browser)

Bases: object

Manage top-level pages and windows through one synchronous contract.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Open and activate a second page:

page = browser.pages.open("https://example.com/details")
browser.pages.activate(page)

Bind page operations to one browser context.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Browser creates this service once:

pages = BrowserPages(browser)

all() → list[BrowserPage]

Return a current page snapshot in provider order.

Returns

Type	Description
list[BrowserPage]	Page descriptors.

Raises

Exception	Description
UnsupportedCapabilityError	Top-level pages are unavailable.

Examples

Inspect every open page:

for page in browser.pages.all():
    print(page.title)

property current: BrowserPage

Return the active top-level page.

Returns

Active page descriptor.

Raises

Exception	Description
UnsupportedCapabilityError	Top-level pages are unavailable.

Examples

Preserve the current page before opening another:

original = browser.pages.current

open(url: str | None = None, *, activate: bool = True) → BrowserPage

Open one new top-level page.

Parameters

Name	Type	Description
url	str | None	Optional initial URL.
activate	bool	Make the new page active for subsequent facade calls.

Returns

Type	Description
BrowserPage	New page descriptor.

Raises

Exception	Description
UnsupportedCapabilityError	Top-level pages are unavailable.

Examples

Open a blank page without changing active business context:

page = browser.pages.open(activate=False)

new(url: str | None = None, *, background: bool = False, timeout: float | None = None) → BrowserPage

Open a new page using the neutral workbook contract.

Parameters

Name	Type	Description
url	str | None	Optional initial URL.
background	bool	Keep the previous page active.
timeout	float | None	Optional navigation timeout in seconds.

Returns

Type	Description
BrowserPage	New page descriptor.

Examples

page = browser.pages.new("https://example.com", background=True).

activate(page: BrowserPage | str | int) → BrowserPage

Activate a page by descriptor, identifier, or index.

Parameters

Name	Type	Description
page	BrowserPage | str | int	Page descriptor, identifier, or zero-based index.

Returns

Type	Description
BrowserPage	Activated page descriptor.

Raises

Exception	Description
BrowserError	No matching page exists.
UnsupportedCapabilityError	Top-level pages are unavailable.

Examples

Activate the second page:

browser.pages.activate(1)

switch(page_or_index: BrowserPage | str | int) → BrowserPage

Activate a page by descriptor, identifier, or index.

Parameters

Name	Type	Description
page_or_index	BrowserPage | str | int	Page reference.

Returns

Type	Description
BrowserPage	Activated page.

Examples

browser.pages.switch(1).

close(page_or_index: BrowserPage | str | int | None = None) → None

Close one page and return the remaining active page.

Parameters

Name	Type	Description
page_or_index	BrowserPage | str | int | None	Page to close; defaults to the active page.

Returns

Type	Description
None	None.

Raises

Exception	Description
BrowserError	No requested page exists.
UnsupportedCapabilityError	Top-level pages are unavailable.

Examples

Close a temporary page and continue on another:

active = browser.pages.close(temporary)

find(*, url: str | None = None, title: str | None = None) → BrowserPage | None

Find the first page matching URL and title globs.

Parameters

Name	Type	Description
url	str | None	Optional URL glob.
title	str | None	Optional title glob.

Returns

Type	Description
BrowserPage | None	Matching page or None.

Examples

page = browser.pages.find(url="*/results*").

wait_new(*, timeout: float, predicate: Callable[[BrowserPage], bool] | None = None) → BrowserPage

Execute an action and wait for exactly one newly observable page.

Parameters

Name	Type	Description
timeout	float	Wait budget in seconds.
predicate	Callable[[BrowserPage], bool] | None	Optional page predicate.

Returns

Type	Description
BrowserPage	Newly observed page descriptor.

Raises

Exception	Description
WaitTimeoutError	No new page appears before the deadline.
UnsupportedCapabilityError	Top-level pages are unavailable.

Examples

Capture a page opened by a link:

page = browser.pages.wait_new(lambda: link.click())