l.s.b.StorageDriver(BaseDriver) : class documentation

@keyword    key:    API key or username to used
@type       key:    str

@keyword    secret: Secret password to be used
@type       secret: str

@keyword    secure: Weither to use HTTPS or HTTP. Note: Some providers
                    only support HTTPS, and it is on by default.
@type       secure: bool

@keyword    host: Override hostname used for connections.
@type       host: str

@keyword    port: Override port used for connections.
@type       port: int

@keyword    api_version: Optional API version. Only used by drivers
                         which support multiple API versions.
@type       api_version: str

@requires: key, secret

Return a list of containers.

@return: A list of Container instances.

Return a list of objects for the given container.

@type container: C{Container}
@param container: Container instance

@return: A list of Object instances.

Return a container instance.

@type container_name: C{str}
@param container_name: Container name.

@return: C{Container} instance.

Return a container CDN URL.

@type container: C{Container}
@param container: Container instance

@return: A CDN URL for this container.

Return an object instance.

@type container_name: C{str}
@param container_name: Container name.

@type object_name: C{str}
@param object_name: Object name.

@return: C{Object} instance.

Return a container CDN URL.

@type obj: C{Object}
@param obj: Object instance

@return: A CDN URL for this object.

Download an object to the specified destination path.

@type obj: C{Object}
@param obj: Object instance.

@type destination_path: C{str}
@param destination_path: Full path to a file or a directory where the
                        incoming file will be saved.

@type overwrite_existing: C{bool}
@param overwrite_existing: True to overwrite an existing file, defaults to False.

@type delete_on_failure: C{bool}
@param delete_on_failure: True to delete a partially downloaded file if
the download was not successful (hash mismatch / file size).

@rtype: C{bool}
@return: True if an object has been successfully downloaded, False
otherwise.

Return a generator which yields object data.

@type obj: C{Object}
@param obj: Object instance

@type chunk_size: C{int}
@param chunk_size: Optional chunk size (in bytes).

Upload an object currently located on a disk.

@type file_path: C{str}
@param file_path: Path to the object on disk.

@type container: C{Container}
@param container: Destination container.

@type object_name: C{str}
@param object_name: Object name.

@type extra: C{dict}
@param extra: (optional) Extra attributes (driver specific).

Upload an object using an iterator.

If a provider supports it, chunked transfer encoding is used and you
don't need to know in advance the amount of data to be uploaded.

Otherwise if a provider doesn't support it, iterator will be exhausted
so a total size for data to be uploaded can be determined.

Note: Exhausting the iterator means that the whole data must be buffered
in memory which might result in memory exhausting when uploading a very
large object.

If a file is located on a disk you are advised to use upload_object
function which uses fs.stat function to determine the file size and it
doesn't need to buffer whole object in the memory.

@type iterator: C{object}
@param iterator: An object which implements the iterator interface.

@type container: C{Container}
@param container: Destination container.

@type object_name: C{str}
@param object_name: Object name.

@type extra: C{dict}
@param extra: (optional) Extra attributes (driver specific).

Note: This dictionary must contain a 'content_type' key which represents
a content type of the stored object.

Delete an object.

@type obj: C{Object}
@param obj: Object instance.

@return: C{bool} True on success.

Create a new container.

@type container_name: C{str}
@param container_name: Container name.

@return: C{Container} instance on success.

Delete a container.

@type container: C{Container}
@param container: Container instance

@rtype: C{bool}
@return: True on success, False otherwise.

Call passed callback and start transfer of the object'

@type obj: C{Object}
@param obj: Object instance.

@type callback: C{Function}
@param callback: Function which is called with the passed callback_kwargs

@type callback_kwargs: C{dict}
@param callback_kwargs: Keyword arguments which are passed to the callback.

@typed response: C{Response}
@param response: Response instance.

@type success_status_code: C{int}
@param success_status_code: Status code which represents a successful
                            transfer (defaults to httplib.OK)

@rtype: C{bool}
@return: True on success, False otherwise.

Save object to the provided path.

@type response: C{RawResponse}
@param response: RawResponse instance.

@type obj: C{Object}
@param obj: Object instance.

@type destination_path: C{Str}
@param destination_path: Destination directory.

@type delete_on_failure: C{bool}
@param delete_on_failure: True to delete partially downloaded object if
                          the download fails.
@type overwrite_existing: C{bool}
@param overwrite_existing: True to overwrite a local path if it already
                           exists.

@type chunk_size: C{int}
@param chunk_size: Optional chunk size (defaults to L{libcloud.storage.base.CHUNK_SIZE}, 8kb)

@rtype: C{bool}
@return: True on success, False otherwise.

Helper function for setting common request headers and calling the
passed in callback which uploads an object.

Upload data stored in a string.

@type response: C{RawResponse}
@param response: RawResponse object.

@type data: C{str}
@param data: Data to upload.

@type calculate_hash: C{boolean}
@param calculate_hash: True to calculate hash of the transfered data.
                       (defauls to True).

@rtype: C{tuple}
@return: First item is a boolean indicator of success, second
         one is the uploaded data MD5 hash and the third one
         is the number of transferred bytes.

Stream a data over an http connection.

@type response: C{RawResponse}
@param response: RawResponse object.

@type iterator: C{}
@param response: An object which implements an iterator interface
                 or a File like object with read method.

@type chunked: C{boolean}
@param chunked: True if the chunked transfer encoding should be used
                (defauls to False).

@type calculate_hash: C{boolean}
@param calculate_hash: True to calculate hash of the transfered data.
                       (defauls to True).

@type chunk_size: C{int}
@param chunk_size: Optional chunk size (defaults to CHUNK_SIZE)

@rtype: C{tuple}
@return: First item is a boolean indicator of success, second
         one is the uploaded data MD5 hash and the third one
         is the number of transferred bytes.

Upload a file to the server.

@type response: C{RawResponse}
@param response: RawResponse object.

@type file_path: C{str}
@param file_path: Path to a local file.

@type iterator: C{}
@param response: An object which implements an iterator interface (File
                 object, etc.)

@rtype: C{tuple}
@return: First item is a boolean indicator of success, second
         one is the uploaded data MD5 hash and the third one
         is the number of transferred bytes.

Return instantiated hash function for the hash type supported by
the provider.