google.resumable_media.upload module

Support for resumable uploads.

Also supported here are simple (media) uploads and multipart uploads that contain both metadata and a small file as payload.

class google.resumable_media.upload.MultipartUpload(upload_url, headers=None)

Bases: google.resumable_media.upload._UploadBase

Upload a resource with metadata to a Google API.

A multipart upload sends both metadata and the resource in a single (multipart) request.

Parameters:
  • upload_url (str) – The URL where the content will be uploaded.
  • headers (Optional [ Mapping [ str, str ] ]) – Extra headers that should be sent with the request, e.g. headers for encrypted data.
finished

bool – Flag indicating if the upload has completed.

transmit(transport, data, metadata, content_type)

Transmit the resource to be uploaded.

Parameters:
  • transport (object) – An object which can make authenticated requests.
  • data (bytes) – The resource content to be uploaded.
  • metadata (Mapping [ str, str ]) – The resource metadata, such as an ACL list.
  • content_type (str) – The content type of the resource, e.g. a JPEG image has content type image/jpeg.
Returns:

The HTTP response returned by transport.

Return type:

object

google.resumable_media.upload.PERMANENT_REDIRECT = 308

int – Permanent redirect status code.

It is used by Google services to indicate some (but not all) of a resumable upload has been completed.

http.client.PERMANENT_REDIRECT was added in Python 3.5, so can’t be used in a “general” code base.

For more information, see RFC 7238.

class google.resumable_media.upload.ResumableUpload(upload_url, chunk_size, headers=None)

Bases: google.resumable_media.upload._UploadBase

Initiate and fulfill a resumable upload to a Google API.

A resumable upload sends an initial request with the resource metadata and then gets assigned an upload ID / upload URL to send bytes to. Using the upload URL, the upload is then done in chunks (determined by the user) until all bytes have been uploaded.

Parameters:
  • upload_url (str) – The URL where the resumable upload will be initiated.
  • chunk_size (int) – The size of each chunk used to upload the resource.
  • headers (Optional [ Mapping [ str, str ] ]) – Extra headers that should be sent with the initiate() request, e.g. headers for encrypted data. These will not be sent with transmit_next_chunk() or recover() requests.
Raises:

ValueError – If chunk_size is not a multiple of UPLOAD_CHUNK_SIZE.

bytes_uploaded

int – Number of bytes that have been uploaded.

chunk_size

int – The size of each chunk used to upload the resource.

finished

bool – Flag indicating if the upload has completed.

initiate(transport, stream, metadata, content_type)

Initiate a resumable upload.

Parameters:
  • transport (object) – An object which can make authenticated requests.
  • stream (IO[bytes]) – The stream (i.e. file-like object) that will be uploaded. The stream must be at the beginning (i.e. stream.tell() == 0).
  • metadata (Mapping [ str, str ]) – The resource metadata, such as an ACL list.
  • content_type (str) – The content type of the resource, e.g. a JPEG image has content type image/jpeg.
Returns:

The HTTP response returned by transport.

Return type:

object

invalid

bool – Indicates if the upload is in an invalid state.

This will occur if a call to transmit_next_chunk() fails. To recover from such a failure, call recover().

recover(transport)

Recover from a failure.

This method should be used when a ResumableUpload is in an invalid state due to a request failure.

This will verify the progress with the server and make sure the current upload is in a valid state before transmit_next_chunk() can be used again.

Parameters:transport (object) – An object which can make authenticated requests.
Returns:The HTTP response returned by transport.
Return type:object
resumable_url

Optional [ str ] – The URL of the in-progress resumable upload.

total_bytes

Optional [ int ] – The total number of bytes to be uploaded.

transmit_next_chunk(transport)

Transmit the next chunk of the resource to be uploaded.

In the case of failure, an exception is thrown that preserves the failed response:

>>> error = None
>>> try:
...     upload.transmit_next_chunk(transport)
... except resumable_media.InvalidResponse as caught_exc:
...     error = caught_exc
...
>>> error
InvalidResponse('Request failed with status code', 400,
                'Expected one of', <HTTPStatus.OK: 200>, 308)
>>> error.response
<Response [400]>
Parameters:transport (object) – An object which can make authenticated requests.
Returns:The HTTP response returned by transport.
Return type:object
Raises:InvalidResponse – If the status code is not 200 or 308.
class google.resumable_media.upload.SimpleUpload(upload_url, headers=None)

Bases: google.resumable_media.upload._UploadBase

Upload a resource to a Google API.

A simple media upload sends no metadata and completes the upload in a single request.

Parameters:
  • upload_url (str) – The URL where the content will be uploaded.
  • headers (Optional [ Mapping [ str, str ] ]) – Extra headers that should be sent with the request, e.g. headers for encrypted data.
finished

bool – Flag indicating if the upload has completed.

transmit(transport, data, content_type)

Transmit the resource to be uploaded.

Parameters:
  • transport (object) – An object which can make authenticated requests.
  • data (bytes) – The resource content to be uploaded.
  • content_type (str) – The content type of the resource, e.g. a JPEG image has content type image/jpeg.
Returns:

The HTTP response returned by transport.

Return type:

object

google.resumable_media.upload.UPLOAD_CHUNK_SIZE = 262144

int – Chunks in a resumable upload must come in multiples of 256 KB.