ddp_utils.browser.facade.downloads

import ddp_utils.browser.facade.downloads

Backend-neutral download lifecycle and blob persistence services.

class ddp_utils.browser.facade.downloads.BrowserDownload(service: BrowserDownloads, identifier: str, native: Any = None, source_path: Path | None = None, url: str | None = None, filename: str | None = None, started_at: float = 0.0, completed_at: float | None = None, _failure: str | None = None, _deleted: bool = False)

Bases: object

Represent one download from start through durable persistence.

Parameters

Name	Type	Description
service	BrowserDownloads	Owning downloads service.
identifier	str	Stable facade identifier.
native	Any	Native Playwright download when available.
source_path	Path | None	Observed Selenium download path when available.
url	str | None	Source URL when known.
filename	str | None	Suggested filename.
started_at	float	Unix start timestamp.

Examples

Wait and save through the same object on every backend:

download.wait_complete().save_as("reports/result.pdf")

property id: str

Return the stable download identifier.

Returns

Facade identifier.

Examples

Correlate the download with project diagnostics:

print(download.id)

property state: str

Return started, completed, failed, or deleted.

Returns

Normalized lifecycle state.

Examples

Branch after a callback:

if download.state == "completed":
    process(download.path)

property suggested_filename: str | None

Return the provider-suggested filename.

Returns

Filename or None.

Examples

Build a destination path:

name = download.suggested_filename or "download.bin"

property mime_type: str | None

Guess MIME type from the suggested filename.

Returns

Guessed MIME type or None.

Examples

Validate a PDF-oriented workflow:

assert download.mime_type == "application/pdf"

property path: Path | None

Return an existing provider path when available.

Returns

Existing path or None while incomplete/unavailable.

Examples

Process an already completed file:

if download.path:
    parse(download.path)

property failure: str | None

Return the provider failure reason without raising.

Returns

Failure text or None.

Examples

Include a failure in diagnostics:

print(download.failure)

wait_complete(*, timeout: float | None = None) → BrowserDownload

Wait for successful completion.

Parameters

Name	Type	Description
timeout	float | None	Optional deadline in seconds.

Returns

Type	Description
BrowserDownload	This completed download.

Raises

Exception	Description
DownloadTimeoutError	Completion exceeds the deadline.
DownloadFailedError	Provider reports failure.

Examples

Wait with the configured default budget:

download.wait_complete()

save_as(path: str | Path, *, timeout: float | None = None, overwrite: bool = False) → Path

Persist the completed download at an explicit destination.

Parameters

Name	Type	Description
path	str | Path	Destination file path.
timeout	float | None	Optional completion deadline.
overwrite	bool	Replace an existing destination when true.

Returns

Type	Description
Path	Absolute destination path.

Raises

Exception	Description
DownloadError	Download fails or the file cannot be persisted.

Examples

Save using a business-defined name:

saved = download.save_as("reports/case-42.pdf")

cancel() → None

Cancel a provider download when supported.

Raises

Exception	Description
DownloadFailedError	Selenium cannot cancel this download safely.

Examples

Cancel an unwanted Playwright download:

download.cancel()

delete(*, include_partial: bool = False) → bool

Delete the downloaded file when it exists.

Parameters

Name	Type	Description
include_partial	bool	Permit deletion before completed state.

Returns

Type	Description
bool	True when a file was removed.

Examples

Remove a temporary artifact:

removed = download.delete(include_partial=False)

class ddp_utils.browser.facade.downloads.BrowserDownloads(browser: Browser)

Bases: object

Track download start/completion and persist browser blob URLs.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Subscribe before clicking a download control:

browser.downloads.on_start(lambda item: print(item.url))
button.click()
download = browser.downloads.wait_start()

Bind download state and provider listeners to one browser.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Browser creates this service once:

downloads = BrowserDownloads(browser)

all() → list[BrowserDownload]

Return every tracked download in start order.

Returns

Type	Description
list[BrowserDownload]	Detached download snapshot.

Examples

Inspect the whole session:

downloads = browser.downloads.all()

property latest: BrowserDownload | None

Return the latest tracked download.

Returns

Last download or None.

Examples

Reuse the most recent artifact:

download = browser.downloads.latest

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

Wait for the next matching download to start.

Parameters

Name	Type	Description
timeout	float	Start deadline in seconds.
predicate	Callable[[BrowserDownload], bool] | None	Optional download filter.

Returns

Type	Description
BrowserDownload	Started download.

Examples

Capture a click-triggered download:

download = browser.downloads.wait(timeout=30)

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

Wait for a new download start.

Parameters

Name	Type	Description
timeout	float	Start deadline in seconds.
predicate	Callable[[BrowserDownload], bool] | None	Optional download filter.

Returns

Type	Description
BrowserDownload	Newly observed download.

Raises

Exception	Description
DownloadTimeoutError	No download starts before the deadline.

Examples

Wait after an asynchronous trigger:

download = browser.downloads.wait_start(timeout=30)

wait_complete(download: BrowserDownload | None = None, *, timeout: float, predicate: Callable[[BrowserDownload], bool] | None = None) → BrowserDownload

Wait for a chosen or latest download to complete.

Parameters

Name	Type	Description
download	BrowserDownload | None	Download to wait for; defaults to latest.
timeout	float	Completion deadline in seconds.
predicate	Callable[[BrowserDownload], bool] | None	Optional download filter.

Returns

Type	Description
BrowserDownload	Completed download.

Raises

Exception	Description
DownloadFailedError	No download exists.

Examples

Wait for the latest download:

browser.downloads.wait_complete()

path(download: BrowserDownload | None = None) → Path | None

Return the path of a chosen or latest download.

Parameters

Name	Type	Description
download	BrowserDownload | None	Download to inspect; defaults to latest.

Returns

Type	Description
Path | None	Existing path or None.

Examples

Read a completed file path:

path = browser.downloads.path()

save_as(download: BrowserDownload, path: str | Path) → Path

Save a chosen or latest download to a destination.

Parameters

Name	Type	Description
download	BrowserDownload	Download to save.
path	str | Path	Destination path.

Returns

Type	Description
Path	Absolute destination path.

Raises

Exception	Description
DownloadFailedError	No download exists.

Examples

Save the latest artifact:

browser.downloads.save_as(download, "report.pdf")

cancel(download: BrowserDownload | None = None) → None

Cancel a chosen or latest download.

Parameters

Name	Type	Description
download	BrowserDownload | None	Download to cancel; defaults to latest.

Raises

Exception	Description
DownloadFailedError	No download exists or cancellation unsupported.

Examples

Cancel the latest download:

browser.downloads.cancel()

delete(download: BrowserDownload | None = None) → bool

Delete a chosen or latest downloaded file.

Parameters

Name	Type	Description
download	BrowserDownload | None	Download to delete; defaults to latest.

Returns

Type	Description
bool	Whether a file was removed.

Examples

Delete a temporary download:

browser.downloads.delete()

suggested_filename(download: BrowserDownload | None = None) → str | None

Return a chosen or latest suggested filename.

Parameters

Name	Type	Description
download	BrowserDownload | None	Download to inspect; defaults to latest.

Returns

Type	Description
str | None	Suggested filename or None.

Examples

Select a business destination name:

name = browser.downloads.suggested_filename()

failure(download: BrowserDownload | None = None) → str | None

Return a chosen or latest failure reason.

Parameters

Name	Type	Description
download	BrowserDownload | None	Download to inspect; defaults to latest.

Returns

Type	Description
str | None	Failure reason or None.

Examples

Log a provider failure:

print(browser.downloads.failure())

on_start(callback: Callable[[BrowserDownload], Any]) → BrowserSubscription

Subscribe to download-start events.

Parameters

Name	Type	Description
callback	Callable[[BrowserDownload], Any]	Callable receiving the new download.

Returns

Type	Description
BrowserSubscription	Removable subscription.

Examples

Record every download URL:

browser.downloads.on_start(lambda item: print(item.url))

on_complete(callback: Callable[[BrowserDownload], Any]) → BrowserSubscription

Subscribe to observed completion events.

Parameters

Name	Type	Description
callback	Callable[[BrowserDownload], Any]	Callable receiving a completed download.

Returns

Type	Description
BrowserSubscription	Removable subscription.

Examples

Process completed files:

browser.downloads.on_complete(process)

on_failure(callback: Callable[[BrowserDownload], Any]) → BrowserSubscription

Subscribe to observed failure events.

Parameters

Name	Type	Description
callback	Callable[[BrowserDownload], Any]	Callable receiving a failed download.

Returns

Type	Description
BrowserSubscription	Removable subscription.

Examples

Preserve failure diagnostics:

browser.downloads.on_failure(log_failure)

off(subscription: BrowserSubscription) → None

Remove a download subscription idempotently.

Parameters

Name	Type	Description
subscription	BrowserSubscription	Subscription returned by an on_* method.

Examples

Remove a temporary listener:

browser.downloads.off(subscription)

save_blob(source: Any, path: str | Path, *, frame: Any = None, timeout: float | None = None, expected_mime: str | None = None, validate: Callable[[bytes, str], Any] | None = None, overwrite: bool = False) → Path

Read a blob URL in its owning page and save durable bytes.

Parameters

Name	Type	Description
source	Any	Blob URL or element exposing src, href, or data.
path	str | Path	Destination path.
frame	Any	Optional owning frame.
timeout	float | None	Optional script deadline.
expected_mime	str | None	Optional required MIME prefix or exact value.
validate	Callable[[bytes, str], Any] | None	Optional payload validator receiving bytes and MIME type.
overwrite	bool	Replace an existing destination when true.

Returns

Type	Description
Path	Absolute saved path.

Raises

Exception	Description
BlobAccessError	Blob can no longer be read.
BlobValidationError	MIME validation fails.

Examples

Save a page-created PDF blob:

browser.downloads.save_blob(blob_url, "result.pdf")

save_blob_pdf(source: Any, path: str | Path, *, frame: Any = None, timeout: float | None = None, validate: bool = True, overwrite: bool = False) → Path

Save and validate a blob as a real PDF file.

Parameters

Name	Type	Description
source	Any	Blob URL or blob-backed element.
path	str | Path	Destination PDF path.
frame	Any	Optional owning frame.
timeout	float | None	Optional script deadline.
validate	bool	Verify the PDF signature when true.
overwrite	bool	Replace an existing destination when true.

Returns

Type	Description
Path	Absolute saved path.

Raises

Exception	Description
BlobValidationError	Payload does not begin with the PDF signature.

Examples

Persist an embedded PDF blob:

pdf = browser.downloads.save_blob_pdf(blob_url, "case.pdf")

close() → None

Remove native and facade download listeners.

Examples

Browser invokes this during cleanup:

browser.downloads.close()