Updated Branches: refs/heads/trunk 937e33a27 -> 73bd38289
Port base storage api docstrings to Sphinx format, add storage sphinx api docs. Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/a8627b48 Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/a8627b48 Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/a8627b48 Branch: refs/heads/trunk Commit: a8627b48bf0ca9c97aea77600e81dce7dd38b0ae Parents: 937e33a Author: Tomaz Muraus <[email protected]> Authored: Sat Aug 3 17:07:07 2013 +0200 Committer: Tomaz Muraus <[email protected]> Committed: Sat Aug 3 17:07:07 2013 +0200 ---------------------------------------------------------------------- docs/storage/api.rst | 5 + libcloud/storage/base.py | 325 +++++++++++++++++++++--------------------- 2 files changed, 167 insertions(+), 163 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8627b48/docs/storage/api.rst ---------------------------------------------------------------------- diff --git a/docs/storage/api.rst b/docs/storage/api.rst new file mode 100644 index 0000000..f44b0b4 --- /dev/null +++ b/docs/storage/api.rst @@ -0,0 +1,5 @@ +Storage Base API +================ + +.. autoclass:: libcloud.storage.base.StorageDriver + :members: http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8627b48/libcloud/storage/base.py ---------------------------------------------------------------------- diff --git a/libcloud/storage/base.py b/libcloud/storage/base.py index f0e4e3a..4a965b8 100644 --- a/libcloud/storage/base.py +++ b/libcloud/storage/base.py @@ -44,26 +44,26 @@ class Object(object): def __init__(self, name, size, hash, extra, meta_data, container, driver): """ - @param name: Object name (must be unique per container). - @type name: C{str} + :param name: Object name (must be unique per container). + :type name: ``str`` - @param size: Object size in bytes. - @type size: C{int} + :param size: Object size in bytes. + :type size: ``int`` - @param hash Object hash. - @type hash: C{str} + :param hash Object hash. + :type hash: ``str`` - @param container: Object container. - @type container: L{Container} + :param container: Object container. + :type container: :class:`Container` - @param extra: Extra attributes. - @type extra: C{dict} + :param extra: Extra attributes. + :type extra: ``dict`` - @param meta_data: Optional object meta data. - @type meta_data: C{dict} + :param meta_data: Optional object meta data. + :type meta_data: ``dict`` - @param driver: StorageDriver instance. - @type driver: L{StorageDriver} + :param driver: StorageDriver instance. + :type driver: :class:`StorageDriver` """ self.name = name @@ -104,14 +104,14 @@ class Container(object): def __init__(self, name, extra, driver): """ - @param name: Container name (must be unique). - @type name: C{str} + :param name: Container name (must be unique). + :type name: ``str`` - @param extra: Extra attributes. - @type extra: C{dict} + :param extra: Extra attributes. + :type extra: ``dict`` - @param driver: StorageDriver instance. - @type driver: L{StorageDriver} + :param driver: StorageDriver instance. + :type driver: :class:`StorageDriver` """ self.name = name @@ -183,8 +183,8 @@ class StorageDriver(BaseDriver): """ Return a generator of containers for the given account - @return: A generator of Container instances. - @rtype: C{generator} of L{Container} + :return: A generator of Container instances. + :rtype: ``generator`` of :class:`Container` """ raise NotImplementedError( 'iterate_containers not implemented for this driver') @@ -193,8 +193,8 @@ class StorageDriver(BaseDriver): """ Return a list of containers. - @return: A list of Container instances. - @rtype: C{list} of L{Container} + :return: A list of Container instances. + :rtype: ``list`` of :class:`Container` """ return list(self.iterate_containers()) @@ -202,11 +202,11 @@ class StorageDriver(BaseDriver): """ Return a generator of objects for the given container. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @return: A generator of Object instances. - @rtype: C{generator} of L{Object} + :return: A generator of Object instances. + :rtype: ``generator`` of :class:`Object` """ raise NotImplementedError( 'iterate_container_objects not implemented for this driver') @@ -215,11 +215,11 @@ class StorageDriver(BaseDriver): """ Return a list of objects for the given container. - @param container: Container instance - @type container: L{Container} + :param container: Container instance. + :type container: :class:`Container` - @return: A list of Object instances. - @rtype: C{list} of L{Object} + :return: A list of Object instances. + :rtype: ``list`` of :class:`Object` """ return list(self.iterate_container_objects(container)) @@ -227,11 +227,11 @@ class StorageDriver(BaseDriver): """ Return a container instance. - @param container_name: Container name. - @type container_name: C{str} + :param container_name: Container name. + :type container_name: ``str`` - @return: L{Container} instance. - @rtype: L{Container} + :return: :class:`Container` instance. + :rtype: :class:`Container` """ raise NotImplementedError( 'get_object not implemented for this driver') @@ -240,11 +240,11 @@ class StorageDriver(BaseDriver): """ Return a container CDN URL. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @return: A CDN URL for this container. - @rtype: C{str} + :return: A CDN URL for this container. + :rtype: ``str`` """ raise NotImplementedError( 'get_container_cdn_url not implemented for this driver') @@ -253,14 +253,14 @@ class StorageDriver(BaseDriver): """ Return an object instance. - @param container_name: Container name. - @type container_name: C{str} + :param container_name: Container name. + :type container_name: ``str`` - @param object_name: Object name. - @type object_name: C{str} + :param object_name: Object name. + :type object_name: ``str`` - @return: L{Object} instance. - @rtype: L{Object} + :return: :class:`Object` instance. + :rtype: :class:`Object` """ raise NotImplementedError( 'get_object not implemented for this driver') @@ -269,11 +269,11 @@ class StorageDriver(BaseDriver): """ Return a object CDN URL. - @param obj: Object instance - @type obj: L{Object} + :param obj: Object instance + :type obj: :class:`Object` - @return: A CDN URL for this object. - @rtype: C{str} + :return: A CDN URL for this object. + :rtype: ``str`` """ raise NotImplementedError( 'get_object_cdn_url not implemented for this driver') @@ -282,10 +282,10 @@ class StorageDriver(BaseDriver): """ Enable container CDN. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @rtype: C{bool} + :rtype: ``bool`` """ raise NotImplementedError( 'enable_container_cdn not implemented for this driver') @@ -294,10 +294,10 @@ class StorageDriver(BaseDriver): """ Enable object CDN. - @param obj: Object instance - @type obj: L{Object} + :param obj: Object instance + :type obj: :class:`Object` - @rtype: C{bool} + :rtype: ``bool`` """ raise NotImplementedError( 'enable_object_cdn not implemented for this driver') @@ -307,24 +307,25 @@ class StorageDriver(BaseDriver): """ Download an object to the specified destination path. - @param obj: Object instance. - @type obj: L{Object} + :param obj: Object instance. + :type obj: :class:`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 destination_path: Full path to a file or a directory where the + incoming file will be saved. + :type destination_path: ``str`` - @param overwrite_existing: True to overwrite an existing file, - defaults to False. - @type overwrite_existing: C{bool} + :param overwrite_existing: True to overwrite an existing file, + defaults to False. + :type overwrite_existing: ``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} + :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: ``bool`` - @return: True if an object has been successfully downloaded, False - otherwise. - @rtype: C{bool} + :return: True if an object has been successfully downloaded, False + otherwise. + :rtype: ``bool`` """ raise NotImplementedError( 'download_object not implemented for this driver') @@ -333,13 +334,11 @@ class StorageDriver(BaseDriver): """ Return a generator which yields object data. - @param obj: Object instance - @type obj: L{Object} + :param obj: Object instance + :type obj: :class:`Object` - @param chunk_size: Optional chunk size (in bytes). - @type chunk_size: C{int} - - @rtype: C{object} + :param chunk_size: Optional chunk size (in bytes). + :type chunk_size: ``int`` """ raise NotImplementedError( 'download_object_as_stream not implemented for this driver') @@ -349,22 +348,22 @@ class StorageDriver(BaseDriver): """ Upload an object currently located on a disk. - @param file_path: Path to the object on disk. - @type file_path: C{str} + :param file_path: Path to the object on disk. + :type file_path: ``str`` - @param container: Destination container. - @type container: L{Container} + :param container: Destination container. + :type container: :class:`Container` - @param object_name: Object name. - @type object_name: C{str} + :param object_name: Object name. + :type object_name: ``str`` - @param verify_hash: Verify hash - @type verify_hash: C{bool} + :param verify_hash: Verify hash + :type verify_hash: ``bool`` - @param extra: (optional) Extra attributes (driver specific). - @type extra: C{dict} + :param extra: Extra attributes (driver specific). (optional) + :type extra: ``dict`` - @rtype: C{object} + :rtype: :class:`Object` """ raise NotImplementedError( 'upload_object not implemented for this driver') @@ -389,21 +388,21 @@ class StorageDriver(BaseDriver): 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 iterator: :class:`object` + :param iterator: An object which implements the iterator interface. - @type container: L{Container} - @param container: Destination container. + :type container: :class:`Container` + :param container: Destination container. - @type object_name: C{str} - @param object_name: Object name. + :type object_name: ``str`` + :param object_name: Object name. - @type extra: C{dict} - @param extra: (optional) Extra attributes (driver specific). Note: + :type extra: ``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} + :rtype: C{object} """ raise NotImplementedError( 'upload_object_via_stream not implemented for this driver') @@ -412,11 +411,11 @@ class StorageDriver(BaseDriver): """ Delete an object. - @type obj: L{Object} - @param obj: Object instance. + :type obj: :class:`Object` + :param obj: Object instance. - @return: C{bool} True on success. - @rtype: C{bool} + :return: ``bool`` True on success. + :rtype: ``bool`` """ raise NotImplementedError( 'delete_object not implemented for this driver') @@ -425,11 +424,11 @@ class StorageDriver(BaseDriver): """ Create a new container. - @type container_name: C{str} - @param container_name: Container name. + :type container_name: ``str`` + :param container_name: Container name. - @return: C{Container} instance on success. - @rtype: L{Container} + :return: Container instance on success. + :rtype: :class:`Container` """ raise NotImplementedError( 'create_container not implemented for this driver') @@ -438,11 +437,11 @@ class StorageDriver(BaseDriver): """ Delete a container. - @type container: L{Container} - @param container: Container instance + :type container: :class:`Container` + :param container: Container instance - @return: True on success, False otherwise. - @rtype: C{bool} + :return: ``True`` on success, ``False`` otherwise. + :rtype: ``bool`` """ raise NotImplementedError( 'delete_container not implemented for this driver') @@ -452,26 +451,26 @@ class StorageDriver(BaseDriver): """ Call passed callback and start transfer of the object' - @type obj: C{Object} - @param obj: Object instance. + :type obj: :class:`Object` + :param obj: Object instance. - @type callback: C{Function} - @param callback: Function which is called with the passed + :type callback: :class:`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 + :type callback_kwargs: ``dict`` + :param callback_kwargs: Keyword arguments which are passed to the callback. - @typed response: L{Response} - @param response: Response instance. + :typed response: :class:`Response` + :param response: Response instance. - @type success_status_code: C{int} - @param success_status_code: Status code which represents a successful + :type success_status_code: ``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} + :return: ``True`` on success, ``False`` otherwise. + :rtype: ``bool`` """ success_status_code = success_status_code or httplib.OK @@ -491,29 +490,29 @@ class StorageDriver(BaseDriver): """ Save object to the provided path. - @type response: L{RawResponse} - @param response: RawResponse instance. + :type response: :class:`RawResponse` + :param response: RawResponse instance. - @type obj: L{Object} - @param obj: Object instance. + :type obj: :class:`Object` + :param obj: Object instance. - @type destination_path: C{str} - @param destination_path: Destination directory. + :type destination_path: ``str`` + :param destination_path: Destination directory. - @type delete_on_failure: C{bool} - @param delete_on_failure: True to delete partially downloaded object if + :type delete_on_failure: ``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 + :type overwrite_existing: ``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) + :type chunk_size: ``int`` + :param chunk_size: Optional chunk size + (defaults to ``libcloud.storage.base.CHUNK_SIZE``, 8kb) - @return: True on success, False otherwise. - @rtype: C{bool} + :return: ``True`` on success, ``False`` otherwise. + :rtype: ``bool`` """ chunk_size = chunk_size or CHUNK_SIZE @@ -640,18 +639,18 @@ class StorageDriver(BaseDriver): """ Upload data stored in a string. - @type response: C{RawResponse} - @param response: RawResponse object. + :type response: :class:`RawResponse` + :param response: RawResponse object. - @type data: C{str} - @param data: Data to upload. + :type data: ``str`` + :param data: Data to upload. - @type calculate_hash: C{boolean} - @param calculate_hash: True to calculate hash of the transfered data. + :type calculate_hash: ``bool`` + :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 + :rtype: ``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. """ @@ -681,26 +680,26 @@ class StorageDriver(BaseDriver): """ Stream a data over an http connection. - @type response: C{RawResponse} - @param response: RawResponse object. + :type response: :class:`RawResponse` + :param response: RawResponse object. - @type iterator: C{} - @param response: An object which implements an iterator interface + :type iterator: :class:`object` + :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 + :type chunked: ``bool`` + :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. + :type calculate_hash: ``bool`` + :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) + :type chunk_size: ``int`` + :param chunk_size: Optional chunk size (defaults to ``CHUNK_SIZE``) - @rtype: C{tuple} - @return: First item is a boolean indicator of success, second + :rtype: ``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. """ @@ -766,18 +765,18 @@ class StorageDriver(BaseDriver): """ Upload a file to the server. - @type response: C{RawResponse} - @param response: RawResponse object. + :type response: :class:`RawResponse` + :param response: RawResponse object. - @type file_path: C{str} - @param file_path: Path to a local file. + :type file_path: ``str`` + :param file_path: Path to a local file. - @type iterator: C{} - @param response: An object which implements an iterator interface (File + :type iterator: :class:`object` + :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 + :rtype: ``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. """
