Download
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 withCANCELLED_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 theDownload
:estimated-progress property. You can monitor the estimated progress of the download operation by connecting to the notify::estimated-progress signal ofdownload
.
- 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 returnsNone
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.
- 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 callset_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 callset_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.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 beforeDownload
::received-data to notify that destination file has been created successfully atdestination
.- 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 usingsuggested_filename
.Since 2.40, you may handle this signal asynchronously by returning
True
without callingset_destination()
. This indicates intent to eventually callset_destination()
. In this case, the download will not proceed until the destination is set or cancelled withcancel()
.- 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 withcancel()
, this signal is emitted with errorCANCELLED_BY_USER
. The download operation finishes after an error andDownload
::finished signal is emitted after this one.- Parameters:
error – the
Error
that was triggered