GData.UploadStream¶

Subclasses:: None

Methods¶

Inherited:: Gio.OutputStream (29), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (service, domain, method, upload_uri, entry, slug, content_type, cancellable)
class	`new_resumable` (service, domain, method, upload_uri, entry, slug, content_type, content_length, cancellable)
	`get_authorization_domain` ()
	`get_cancellable` ()
	`get_content_length` ()
	`get_content_type` ()
	`get_entry` ()
	`get_method` ()
	`get_response` ()
	`get_service` ()
	`get_slug` ()
	`get_upload_uri` ()

Virtual Methods¶

Inherited:: Gio.OutputStream (15), GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`authorization-domain`	`GData.AuthorizationDomain`	r/w/co	The authorization domain for the upload.
`cancellable`	`Gio.Cancellable`	r/w/co	An optional cancellable used to cancel the entire upload operation.
`content-length`	`int`	r/w/co	The content length (in bytes) of the file being uploaded.
`content-type`	`str`	r/w/co	The content type of the file being uploaded.
`entry`	`GData.Entry`	r/w/co	The entry used for metadata to upload.
`method`	`str`	r/w/co	The HTTP request method to use when uploading the file.
`service`	`GData.Service`	r/w/co	The service which is used to authorize the upload.
`slug`	`str`	r/w/co	The slug of the file being uploaded.
`upload-uri`	`str`	r/w/co	The URI to upload the data and metadata to.

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`Gio.OutputStream`	r

Class Details¶

class GData.UploadStream(**kwargs)¶

Bases:: Gio.OutputStream
Abstract:: No
Structure:: GData.UploadStreamClass

All the fields in the GData.UploadStream structure are private and should never be accessed directly.

New in version 0.5.0.

classmethod new(service, domain, method, upload_uri, entry, slug, content_type, cancellable)¶

Parameters:

service (GData.Service) – a GData.Service
domain (GData.AuthorizationDomain or None) – the GData.AuthorizationDomain to authorize the upload, or None
method (str) – the HTTP method to use
upload_uri (str) – the URI to upload, which must be HTTPS
entry (GData.Entry or None) – the entry to upload as metadata, or None
slug (str) – the file’s slug (filename)
content_type (str) – the content type of the file being uploaded
cancellable (Gio.Cancellable or None) – a Gio.Cancellable for the entire upload stream, or None

Returns:

a new Gio.OutputStream, or None; unref with GObject.Object.unref()

Return type:

Gio.OutputStream

Creates a new GData.UploadStream, allowing a file to be uploaded from a GLib.Data service using standard Gio.OutputStream API.

The HTTP method to use should be specified in method, and will typically be either %SOUP_METHOD_POST (for insertions) or %SOUP_METHOD_PUT (for updates), according to the server and the upload_uri.

If entry is specified, it will be attached to the upload as the entry to which the file being uploaded belongs. Otherwise, just the file written to the stream will be uploaded, and given a default entry as determined by the server.

slug and content_type must be specified before the upload begins, as they describe the file being streamed. slug is the filename given to the file, which will typically be stored on the server and made available when downloading the file again. content_type must be the correct content type for the file, and should be in the service’s list of acceptable content types.

As well as the standard GIO errors, calls to the Gio.OutputStream API on a GData.UploadStream can also return any relevant specific error from GData.ServiceError, or GData.ServiceError.PROTOCOL_ERROR in the general case.

If a Gio.Cancellable is provided in cancellable, the upload operation may be cancelled at any time from another thread using Gio.Cancellable.cancel(). In this case, any ongoing network activity will be stopped, and any pending or future calls to Gio.OutputStream API on the GData.UploadStream will return Gio.IOErrorEnum.CANCELLED. Note that the Gio.Cancellable objects which can be passed to individual Gio.OutputStream operations will not cancel the upload operation proper if cancelled — they will merely cancel that API call. The only way to cancel the upload operation completely is using this cancellable.

Note that network communication won’t begin until the first call to Gio.OutputStream.write() on the GData.UploadStream.

New in version 0.9.0.

classmethod new_resumable(service, domain, method, upload_uri, entry, slug, content_type, content_length, cancellable)¶

Parameters:

service (GData.Service) – a GData.Service
domain (GData.AuthorizationDomain or None) – the GData.AuthorizationDomain to authorize the upload, or None
method (str) – the HTTP method to use
upload_uri (str) – the URI to upload
entry (GData.Entry or None) – the entry to upload as metadata, or None
slug (str) – the file’s slug (filename)
content_type (str) – the content type of the file being uploaded
content_length (int) – the size (in bytes) of the file being uploaded
cancellable (Gio.Cancellable or None) – a Gio.Cancellable for the entire upload stream, or None

Returns:

a new Gio.OutputStream, or None; unref with GObject.Object.unref()

Return type:

Gio.OutputStream

Creates a new resumable GData.UploadStream, allowing a file to be uploaded from a GLib.Data service using standard Gio.OutputStream API. The upload will use GLib.Data's resumable upload API, so should be more reliable than a normal upload (especially if the file is large). See the

GData documentation on resumable uploads for more information.

The HTTP method to use should be specified in method, and will typically be either %SOUP_METHOD_POST (for insertions) or %SOUP_METHOD_PUT (for updates), according to the server and the upload_uri.

If entry is specified, it will be attached to the upload as the entry to which the file being uploaded belongs. Otherwise, just the file written to the stream will be uploaded, and given a default entry as determined by the server.

slug, content_type and content_length must be specified before the upload begins, as they describe the file being streamed. slug is the filename given to the file, which will typically be stored on the server and made available when downloading the file again. content_type must be the correct content type for the file, and should be in the service’s list of acceptable content types. content_length must be the size of the file being uploaded (not including the XML for any associated GData.Entry) in bytes. Zero is accepted if a metadata-only upload is being performed.

As well as the standard GIO errors, calls to the Gio.OutputStream API on a GData.UploadStream can also return any relevant specific error from GData.ServiceError, or GData.ServiceError.PROTOCOL_ERROR in the general case.

If a Gio.Cancellable is provided in cancellable, the upload operation may be cancelled at any time from another thread using Gio.Cancellable.cancel(). In this case, any ongoing network activity will be stopped, and any pending or future calls to Gio.OutputStream API on the GData.UploadStream will return Gio.IOErrorEnum.CANCELLED. Note that the Gio.Cancellable objects which can be passed to individual Gio.OutputStream operations will not cancel the upload operation proper if cancelled — they will merely cancel that API call. The only way to cancel the upload operation completely is using this cancellable.

Note that network communication won’t begin until the first call to Gio.OutputStream.write() on the GData.UploadStream.

New in version 0.13.0.

get_authorization_domain()¶

Returns:: the GData.AuthorizationDomain used to authorize the upload, or None
Return type:: GData.AuthorizationDomain or None

Gets the authorization domain used to authorize the upload, as passed to GData.UploadStream.new(). It may be None if authorization is not needed for the upload.

New in version 0.9.0.

get_cancellable()¶

Returns:: the Gio.Cancellable for the entire upload operation
Return type:: Gio.Cancellable

Gets the Gio.Cancellable for the entire upload operation, GData.UploadStream :cancellable.

New in version 0.8.0.

get_content_length()¶

Returns:: the size of the file being uploaded
Return type:: int

Gets the size (in bytes) of the file being uploaded. This will be -1 for a non-resumable upload, and zero or greater for a resumable upload.

New in version 0.13.0.

get_content_type()¶

Returns:: the content type of the file being uploaded
Return type:: str

Gets the content type of the file being uploaded.

New in version 0.5.0.

get_entry()¶

Returns:: the entry used for metadata, or None
Return type:: GData.Entry

Gets the entry being used to upload metadata, if one was passed to GData.UploadStream.new().

New in version 0.5.0.

get_method()¶

Returns:: the HTTP request method in use
Return type:: str

Gets the HTTP request method being used to upload the file, as passed to GData.UploadStream.new().

New in version 0.7.0.

get_response()¶

Returns:

the server’s response to the upload, or None

length:: return location for the length of the response, or None

Return type:

(str, length: int)

Returns the server’s response to the upload operation performed by the GData.UploadStream. If the operation is still underway, or the server’s response hasn’t been received yet, None is returned and length is set to -1.

If there was an error during the upload operation (but it is complete), None is returned, and length is set to 0.

While it is safe to call this function from any thread at any time during the network operation, the only way to guarantee that the response has been set before calling this function is to have closed the GData.UploadStream by calling Gio.OutputStream.close() on it, without cancelling the close operation. Once the stream has been closed, all network communication is guaranteed to have finished. Note that if a call to Gio.OutputStream.close() is cancelled, Gio.OutputStream.is_closed() will immediately start to return True, even if the GData.UploadStream is still attempting to flush the network buffers asynchronously — consequently, GData.UploadStream.get_response() may still return None and a length of

-1. The only reliable way to determine if the stream has been fully closed in this situation is to check the results of GData.UploadStream.get_response(), rather than Gio.OutputStream.is_closed().

New in version 0.5.0.

get_service()¶

Returns:: the GData.Service used to authorize the upload
Return type:: GData.Service

Gets the service used to authorize the upload, as passed to GData.UploadStream.new().

New in version 0.5.0.

get_slug()¶

Returns:: the slug of the file being uploaded
Return type:: str

Gets the slug (filename) of the file being uploaded.

New in version 0.5.0.

get_upload_uri()¶

Returns:: the URI which the file is being uploaded to
Return type:: str

Gets the URI the file is being uploaded to, as passed to GData.UploadStream.new().

New in version 0.5.0.

Property Details¶

GData.UploadStream.props.authorization_domain¶

Name:: authorization-domain
Type:: GData.AuthorizationDomain
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The authorization domain for the upload, against which the GData.Service :authorizer for the GData.DownloadStream :service should be authorized. This may be None if authorization is not needed for the upload.

New in version 0.9.0.

GData.UploadStream.props.cancellable¶

Name:: cancellable
Type:: Gio.Cancellable
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

An optional cancellable used to cancel the entire upload operation. If a Gio.Cancellable instance isn’t provided for this property at construction time (i.e. to GData.UploadStream.new()), one will be created internally and can be retrieved using GData.UploadStream.get_cancellable() and used to cancel the upload operation with Gio.Cancellable.cancel() just as if it was passed to GData.UploadStream.new().

If the upload operation is cancelled using this Gio.Cancellable, any ongoing network activity will be stopped, and any pending or future calls to Gio.OutputStream API on the GData.UploadStream will return Gio.IOErrorEnum.CANCELLED. Note that the Gio.Cancellable objects which can be passed to individual Gio.OutputStream operations will not cancel the upload operation proper if cancelled — they will merely cancel that API call. The only way to cancel the upload operation completely is using GData.UploadStream :cancellable.

New in version 0.8.0.

GData.UploadStream.props.content_length¶

Name:: content-length
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The content length (in bytes) of the file being uploaded (i.e. as returned by Gio.FileInfo.get_size()). Note that this does not include the length of the XML serialisation of GData.UploadStream :entry, if set.

If this is -1 the upload will be non-resumable; if it is non-negative, the upload will be resumable.

New in version 0.13.0.

GData.UploadStream.props.content_type¶

Name:: content-type
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The content type of the file being uploaded (i.e. as returned by Gio.FileInfo.get_content_type()).

New in version 0.5.0.

GData.UploadStream.props.entry¶

Name:: entry
Type:: GData.Entry
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The entry used for metadata to upload.

New in version 0.5.0.

GData.UploadStream.props.method¶

Name:: method
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The HTTP request method to use when uploading the file.

New in version 0.7.0.

GData.UploadStream.props.service¶

Name:: service
Type:: GData.Service
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The service which is used to authorize the upload, and to which the upload relates.

New in version 0.5.0.

GData.UploadStream.props.slug¶

Name:: slug
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The slug of the file being uploaded. This is usually the display name of the file (i.e. as returned by Gio.FileInfo.get_display_name()).

New in version 0.5.0.

GData.UploadStream.props.upload_uri¶

Name:: upload-uri
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The URI to upload the data and metadata to. This must be HTTPS.

New in version 0.5.0.