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

Whether or not the download is allowed to overwrite an existing file on disk. If this property is False and the destination already exists, the download will fail.

Added in version 2.6.

props.destination: str

The local path to where the download will be saved.

props.estimated_progress: float

An estimate of the percent completion for the download operation. This value will range from 0.0 to 1.0. The value is an estimate based on the total number of bytes expected to be received for a download. If you need a more accurate progress information you can connect to Download::received-data signal to track the progress.

props.response: URIResponse

The URIResponse associated with this download.

Signals

class Download.signals

created_destination(destination: str) → None

This signal is emitted after Download::decide-destination and before Download::received-data to notify that destination file has been created successfully at destination.

Parameters:

destination – the destination

decide_destination(suggested_filename: str) → bool

This signal is emitted after response is received to decide a destination for the download using set_destination(). If this signal is not handled, the file will be downloaded to %G_USER_DIRECTORY_DOWNLOAD directory using suggested_filename.

Since 2.40, you may handle this signal asynchronously by returning True without calling set_destination(). This indicates intent to eventually call set_destination(). In this case, the download will not proceed until the destination is set or cancelled with cancel().

Parameters:

suggested_filename – the filename suggested for the download

failed(error: GError) → None

This signal is emitted when an error occurs during the download operation. The given error, of the domain %WEBKIT_DOWNLOAD_ERROR, contains further details of the failure. If the download is cancelled with cancel(), this signal is emitted with error CANCELLED_BY_USER. The download operation finishes after an error and Download::finished signal is emitted after this one.

Parameters:

error – the Error that was triggered

finished() → None

This signal is emitted when download finishes successfully or due to an error. In case of errors Download::failed signal is emitted before this one.

received_data(data_length: int) → None

This signal is emitted after response is received, every time new data has been written to the destination. It’s useful to know the progress of the download operation.

Parameters:

data_length – the length of data received in bytes