cadrumo.adapters.outbound.aeat.browser.factory module

Default Playwright browser-session factory for auth providers.

Auth providers accept a application.auth.protocols.BrowserSessionFactoryPort: an async callable that returns a application.auth.protocols.BrowserSessionPort. The default factory supplies that protocol with a Playwright-backed BrowserSession, while adapters.outbound.aeat.auth.provider_selection.select_provider() still accepts browser_session_factory=None so tests and callers can inject their own in-process implementations.

This module provides:

• DefaultBrowserSession, the BrowserSessionPort wrapper that owns a Playwright runtime and BrowserSession pair.

• default_browser_session_factory(), the production BrowserSessionFactoryPort entry point used by auth providers and diagnostics.

• shared_playwright_runtime() and opened_browser_page(), the lower-level helpers used by bulk Sede readers that need to reuse one Playwright runtime across several Profile-scoped contexts.

The factory path owns Playwright startup, optional browser extra checks, and best-effort teardown logging. Auth providers remain typed to the protocol, while this module carries the concrete runtime wiring.

class DefaultBrowserSession(playwright, session)

Bases: object

Concrete BrowserSessionPort.

Auth providers depend on the protocol rather than on BrowserSession or Playwright directly. DefaultBrowserSession is the production adapter for that protocol: it owns one Playwright runtime, one BrowserSession, and a Profile through the wrapped session. Its close() method tears the pair down in order, so provider close() paths do not need a second runtime-specific hook.

Parameters:

• playwright (Playwright)

• session (BrowserSession)

property profile: Profile

The Profile associated with the underlying session.

async create_context(*, provisioner=None, storage_state=None)

Delegate context creation to the underlying BrowserSession.

Accepts the same keyword arguments as BrowserSession.create_context() and forwards them unchanged, so certificate provisioners and persisted Cl@ve storage state use the same path as callers that work with BrowserSession directly.

Return type:

BrowserContext

Parameters:

• provisioner (Any | None)

• storage_state (Mapping[str, object] | None)

async navigate(page, url)

Navigate through BrowserSession.navigate().

Return type:

Response | None

Parameters:

• page (Page)

• url (str)

async close()

Close the session and stop the Playwright runtime.

Idempotent after both resources close. BrowserSession.close() runs first, then Playwright.stop(). Each successful teardown is recorded independently so a later call retries only the resource whose previous close failed.

Return type:

None

async default_browser_session_factory(settings)

Start Playwright and return a wrapped DefaultBrowserSession.

The returned object satisfies cadrumo.application.auth.protocols.BrowserSessionPort and owns its Playwright runtime for the full lifetime. The Profile name follows the active bucket when one exists and falls back to a diagnostic sentinel so browser connectivity probes can run before profile setup is complete.

Auth providers pass kind-namespaced encrypted storage state explicitly to BrowserSession.create_context(); the profile path is never loaded implicitly. Call await session.close() when you are done. Auth providers already do that in their close() path.

Return type:

DefaultBrowserSession

Parameters:

settings (Settings)

async create_browser_session(settings, profile)

Start Playwright and return a DefaultBrowserSession.

Wraps a BrowserSession for profile after the optional browser extra has been checked by _start_playwright. If wrapper construction fails after Playwright starts, the partially opened runtime is stopped before the original failure is re-raised.

Return type:

DefaultBrowserSession

Parameters:

• settings (Settings)

• profile (Profile)

shared_playwright_runtime()

Yield a centrally owned Playwright runtime for bulk browser workflows.

Callers that need several Profile-scoped contexts can start Playwright once here and pass the yielded runtime into opened_browser_page(). The context manager owns only the Playwright runtime; each page/context pair is still owned by the helper that opens it.

Return type:

AsyncGenerator[Playwright]

opened_browser_page(playwright, settings, profile, *, provisioner=None, storage_state=None)

Yield a BrowserSession page/context pair and close both.

The helper builds a short-lived BrowserSession around the supplied Playwright runtime, forwards provisioner and storage-state arguments to BrowserSession.create_context(), yields the fresh (page, context) pair, and closes the context and browser session during teardown.

Return type:

AsyncGenerator[tuple[Page, BrowserContext]]

Parameters:

• playwright (playwright.async_api.Playwright)

• settings (Settings)

• profile (Profile)

• provisioner (Any | None)

• storage_state (dict[str, Any] | None)