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: -
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:
-
-
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 theinitiate()
request, e.g. headers for encrypted data. These will not be sent withtransmit_next_chunk()
orrecover()
requests.
Raises: ValueError
– Ifchunk_size
is not a multiple ofUPLOAD_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:
-
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, callrecover()
.
-
recover
(transport)¶ Recover from a failure.
This method should be used when a
ResumableUpload
is in aninvalid
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
-
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: -
finished
¶ bool – Flag indicating if the upload has completed.
-
transmit
(transport, data, content_type)¶ Transmit the resource to be uploaded.
Parameters: Returns: The HTTP response returned by
transport
.Return type:
-
-
google.resumable_media.upload.
UPLOAD_CHUNK_SIZE
= 262144¶ int – Chunks in a resumable upload must come in multiples of 256 KB.