ddp_utils.browser.facade.cookies

import ddp_utils.browser.facade.cookies

Backend-neutral browser cookie service.

class ddp_utils.browser.facade.cookies.BrowserCookies(browser: Browser)

Bases: object

Read and mutate browser cookies through one provider-neutral service.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Store and retrieve one project cookie:

browser.cookies.set("project", "59-IN")
assert browser.cookies.get("project")["value"] == "59-IN"

Bind the cookie service to one browser session.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Browser creates this service once:

cookies = BrowserCookies(browser)

all(*, urls: Any = None) → list[dict[str, Any]]

Return a normalized snapshot of visible browser cookies.

Parameters

Name	Type	Description
urls	Any	Optional URL or URL collection supported by Playwright. Selenium returns cookies visible to the active document and rejects URL filtering.

Returns

Type	Description
list[dict[str, Any]]	Cookie dictionaries in provider order.

Raises

Exception	Description
BrowserConfigurationError	Selenium receives URL filters.
UnsupportedCapabilityError	Cookies are unavailable.

Examples

Preserve all active cookies:

snapshot = browser.cookies.all()

get(name: str, *, url: str | None = None, domain: str | None = None) → dict[str, Any] | None

Return the first cookie with one name.

Parameters

Name	Type	Description
name	str	Cookie name.
url	str | None	Optional URL filter.
domain	str | None	Optional exact domain filter.

Returns

Type	Description
dict[str, Any] | None	Cookie dictionary or None when absent.

Raises

Exception	Description
UnsupportedCapabilityError	Cookies are unavailable.

Examples

Read an optional session cookie:

cookie = browser.cookies.get("session")

set(name: str | None = None, value: Any = None, **cookie: Any) → dict[str, Any]

Add or replace one cookie and return its normalized payload.

Parameters

Name	Type	Description
name	str | None	Cookie name.
value	Any	Value converted to text.
**cookie	Any	Provider-neutral cookie fields such as url, domain, path, expires, http_only, secure, or same_site.

Returns

Type	Description
dict[str, Any]	Payload submitted to the active provider.

Raises

Exception	Description
BrowserConfigurationError	Name is empty or Selenium receives an incompatible URL scope.
UnsupportedCapabilityError	Cookies are unavailable.

Examples

Add a secure domain cookie:

browser.cookies.set(
    "token", "value", domain="example.com", secure=True
)

delete(name: str | None = None, *, url: str | None = None, domain: str | None = None, path: str | None = None) → int

Delete every visible cookie with one name.

Parameters

Name	Type	Description
name	str | None	Cookie name to match. None matches every visible name.
url	str | None	Optional URL forwarded to cookie enumeration. None uses the provider’s active context.
domain	str | None	Exact domain filter. None accepts every domain.
path	str | None	Exact cookie-path filter. None accepts every path.

Returns

Type	Description
int	Number of visible cookie records that matched the filters. Zero is a soft no-op when no record matches.

Raises

Exception	Description
UnsupportedCapabilityError	Cookies are unavailable.

Examples

Remove an obsolete session cookie:

removed = browser.cookies.delete("session")

clear(*, domain: str | None = None, path: str | None = None) → int

Delete all cookies visible to the active provider context.

Parameters

Name	Type	Description
domain	str | None	Exact domain to clear. None includes every domain.
path	str | None	Exact cookie path to clear. None includes every path.

Returns

Type	Description
int	Number of cookie records visible before deletion. When a filter is supplied, this is the number of matching records instead.

Raises

Exception	Description
UnsupportedCapabilityError	Cookies are unavailable.

Examples

Reset authentication state:

removed = browser.cookies.clear()

save(path: str | Path) → Path

Persist cookies as UTF-8 JSON.

Parameters

Name	Type	Description
path	str | Path	Destination file.

Returns

Type	Description
Path	Absolute destination path.

Examples

browser.cookies.save("cookies.json").

load(path: str | Path, *, clear: bool = False) → int

Restore cookies from a JSON file.

Parameters

Name	Type	Description
path	str | Path	Source file.
clear	bool	Clear current cookies first.

Returns

Type	Description
int	Number of restored cookies.

Examples

browser.cookies.load("cookies.json", clear=True).

snapshot() → CookieSnapshot

Capture an in-memory cookie snapshot.

Returns

Type	Description
CookieSnapshot	Immutable snapshot.

Examples

snapshot = browser.cookies.snapshot().

restore(snapshot: CookieSnapshot, *, clear: bool = False) → int

Restore an in-memory cookie snapshot.

Parameters

Name	Type	Description
snapshot	CookieSnapshot	Cookie snapshot.
clear	bool	Clear current cookies first.

Returns

Type	Description
int	Number of restored cookies.

Examples

browser.cookies.restore(snapshot, clear=True).

class ddp_utils.browser.facade.cookies.CookieSnapshot(cookies: tuple[dict[str, Any], ...])

Bases: object

Store a portable immutable cookie snapshot.

Parameters

Name	Type	Description
cookies	tuple[dict[str, Any], ...]	Normalized cookie dictionaries.

Examples

snapshot = browser.cookies.snapshot().