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

Part of libcloud.storage.base View Source View In Hierarchy

Known subclasses: libcloud.storage.drivers.atmos.AtmosDriver, libcloud.storage.drivers.azure_blobs.AzureBlobsStorageDriver, libcloud.storage.drivers.cloudfiles.CloudFilesStorageDriver, libcloud.storage.drivers.dummy.DummyStorageDriver, libcloud.storage.drivers.local.LocalStorageDriver, libcloud.storage.drivers.nimbus.NimbusStorageDriver, libcloud.storage.drivers.s3.S3StorageDriver

A base StorageDriver to derive from.
Method __init__ @param key: API key or username to be used (required) @type key: C{str}
Method iterate_containers Return a generator of containers for the given account
Method list_containers Return a list of containers.
Method iterate_container_objects Return a generator of objects for the given container.
Method list_container_objects Return a list of objects for the given container.
Method get_container Return a container instance.
Method get_container_cdn_url Return a container CDN URL.
Method get_object Return an object instance.
Method get_object_cdn_url Return a object CDN URL.
Method enable_container_cdn Enable container CDN.
Method enable_object_cdn Enable object CDN.
Method download_object Download an object to the specified destination path.
Method download_object_as_stream Return a generator which yields object data.
Method upload_object Upload an object currently located on a disk.
Method upload_object_via_stream Upload an object using an iterator.
Method delete_object Delete an object.
Method create_container Create a new container.
Method delete_container Delete a container.
Method _get_object Call passed callback and start transfer of the object'
Method _save_object Save object to the provided path.
Method _upload_object Helper function for setting common request headers and calling the passed in callback which uploads an object.
Method _upload_data Upload data stored in a string.
Method _stream_data Stream a data over an http connection.
Method _upload_file Upload a file to the server.
Method _get_hash_function Return instantiated hash function for the hash type supported by the provider.

Inherited from BaseDriver:

Method _ex_connection_class_kwargs Return extra connection keyword arguments which are passed to the Connection class constructor.
def __init__(self, key, secret=None, secure=True, host=None, port=None, **kwargs): (source)
@param    key:    API key or username to be used (required)
@type     key:    C{str}

@param    secret: Secret password to be used (required)
@type     secret: C{str}

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

@param    host: Override hostname used for connections.
@type     host: C{str}

@param    port: Override port used for connections.
@type     port: C{int}

@param    api_version: Optional API version. Only used by drivers
                         which support multiple API versions.
@type     api_version: C{str}

@rtype: C{None}
def iterate_containers(self): (source)
Return a generator of containers for the given account

@return: A generator of Container instances.
@rtype: C{generator} of L{Container}
def list_containers(self): (source)
Return a list of containers.

@return: A list of Container instances.
@rtype: C{list} of L{Container}
def iterate_container_objects(self, container): (source)
Return a generator of objects for the given container.

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

@return: A generator of Object instances.
@rtype: C{generator} of L{Object}
def list_container_objects(self, container): (source)
Return a list of objects for the given container.

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

@return: A list of Object instances.
@rtype: C{list} of L{Object}
def get_container(self, container_name): (source)
Return a container instance.

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

@return: L{Container} instance.
@rtype: L{Container}
def get_container_cdn_url(self, container): (source)
Return a container CDN URL.

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

@return: A CDN URL for this container.
@rtype: C{str}
def get_object(self, container_name, object_name): (source)
Return an object instance.

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

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

@return: L{Object} instance.
@rtype: L{Object}
def get_object_cdn_url(self, obj): (source)
Return a object CDN URL.

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

@return: A CDN URL for this object.
@rtype: C{str}
def enable_container_cdn(self, container): (source)
Enable container CDN.

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

@rtype: C{bool}
def enable_object_cdn(self, obj): (source)
Enable object CDN.

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

@rtype: C{bool}
def download_object(self, obj, destination_path, overwrite_existing=False, delete_on_failure=True): (source)
Download an object to the specified destination path.

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

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

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

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

@return: True if an object has been successfully downloaded, False
otherwise.
@rtype: C{bool}
def download_object_as_stream(self, obj, chunk_size=None): (source)
Return a generator which yields object data.

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

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

@rtype: C{object}
def upload_object(self, file_path, container, object_name, extra=None, verify_hash=True): (source)
Upload an object currently located on a disk.

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

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

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

@param verify_hash: Verify hash
@type verify_hash: C{bool}

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

@rtype: C{object}
def upload_object_via_stream(self, iterator, container, object_name, extra=None): (source)
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: L{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.

@rtype: C{object}
def delete_object(self, obj): (source)
Delete an object.

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

@return: C{bool} True on success.
@rtype: C{bool}
def create_container(self, container_name): (source)
Create a new container.

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

@return: C{Container} instance on success.
@rtype: L{Container}
def delete_container(self, container): (source)
Delete a container.

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

@return: True on success, False otherwise.
@rtype: C{bool}
def _get_object(self, obj, callback, callback_kwargs, response, success_status_code=None): (source)
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: L{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)

@return: True on success, False otherwise.
@rtype: C{bool}
def _save_object(self, response, obj, destination_path, overwrite_existing=False, delete_on_failure=True, chunk_size=None): (source)
Save object to the provided path.

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

@type obj: L{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)

@return: True on success, False otherwise.
@rtype: C{bool}
def _upload_object(self, object_name, content_type, upload_func, upload_func_kwargs, request_path, request_method='PUT', headers=None, file_path=None, iterator=None): (source)
Helper function for setting common request headers and calling the
passed in callback which uploads an object.
def _upload_data(self, response, data, calculate_hash=True): (source)
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.
def _stream_data(self, response, iterator, chunked=False, calculate_hash=True, chunk_size=None, data=None): (source)
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.
def _upload_file(self, response, file_path, chunked=False, calculate_hash=True): (source)
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.
def _get_hash_function(self): (source)
Return instantiated hash function for the hash type supported by
the provider.
API Documentation for libcloud, generated by pydoctor at 2013-07-01 17:02:02.