Download

class Download(**properties: Any)

Superclasses: Object

Object used to communicate with the application when downloading.

Download carries information about a download request and response, including a URIRequest and a URIResponse objects. The application may use this object to control the download process, or to simply figure out what is to be downloaded, and handle the download process itself.

Methods

class Download

cancel() → None

Cancels the download.

When the ongoing download operation is effectively cancelled the signal Download::failed is emitted with CANCELLED_BY_USER error.

get_allow_overwrite() → bool

Returns the current value of the Download:allow-overwrite property.

Returns the current value of the Download:allow-overwrite property, which determines whether the download will overwrite an existing file on disk, or if it will fail if the destination already exists.

Added in version 2.6.

get_destination() → str | None

Obtains the destination to which the downloaded file will be written.

You can connect to Download::created-destination to make sure this method returns a valid destination.

get_elapsed_time() → float

Gets the elapsed time in seconds, including any fractional part.

If the download finished, had an error or was cancelled this is the time between its start and the event.

get_estimated_progress() → float

Gets the value of the Download:estimated-progress property. Gets the value of the Download:estimated-progress property. You can monitor the estimated progress of the download operation by connecting to the notify::estimated-progress signal of download.

get_received_data_length() → int

Gets the length of the data already downloaded for download.

Gets the length of the data already downloaded for download in bytes.

get_request() → URIRequest

Retrieves the URIRequest object that backs the download process.

get_response() → URIResponse

Retrieves the URIResponse object that backs the download process.

Retrieves the URIResponse object that backs the download process. This method returns None if called before the response is received from the server. You can connect to notify::response signal to be notified when the response is received.

get_web_view() → WebView

Get the WebView that initiated the download.

set_allow_overwrite(allowed: bool) → None

Sets the Download:allow-overwrite property.

Sets the Download:allow-overwrite property, which determines whether the download may overwrite an existing file on disk, or if it will fail if the destination already exists.

Added in version 2.6.

Parameters:

allowed – the new value for the Download:allow-overwrite property

set_destination(destination: str) → None

Sets the destination to which the downloaded file will be written.

This method should be called before the download transfer starts or it will not have any effect on the ongoing download operation. To set the destination using the filename suggested by the server connect to Download::decide-destination signal and call set_destination(). If you want to set a fixed destination that doesn’t depend on the suggested filename you can connect to notify::response signal and call set_destination().

If Download::decide-destination signal is not handled and destination is not set when the download transfer starts, the file will be saved with the filename suggested by the server in %G_USER_DIRECTORY_DOWNLOAD directory.

Parameters:

destination – the destination

Properties

class Download

props.allow_overwrite: bool

The type of the None singleton.

Added in version 2.6.

props.destination: str

The type of the None singleton.

props.estimated_progress: float

The type of the None singleton.

props.response: URIResponse

The type of the None singleton.

Signals

class Download.signals

created_destination(destination: str) → None

The type of the None singleton.

Parameters:

destination – the destination

decide_destination(suggested_filename: str) → bool

The type of the None singleton.

Parameters:

suggested_filename – the filename suggested for the download

failed(error: GError) → None

The type of the None singleton.

Parameters:

error – the Error that was triggered

finished() → None

The type of the None singleton.

received_data(data_length: int) → None

The type of the None singleton.

Parameters:

data_length – the length of data received in bytes