Updated Branches: refs/heads/trunk 4a0514bb3 -> f01e06373
http://git-wip-us.apache.org/repos/asf/libcloud/blob/f01e0637/libcloud/storage/drivers/azure_blobs.py ---------------------------------------------------------------------- diff --git a/libcloud/storage/drivers/azure_blobs.py b/libcloud/storage/drivers/azure_blobs.py index d693f3d..d11a105 100644 --- a/libcloud/storage/drivers/azure_blobs.py +++ b/libcloud/storage/drivers/azure_blobs.py @@ -84,14 +84,14 @@ class AzureBlobLease(object): """ def __init__(self, driver, object_path, use_lease): """ - @param driver: The Azure storage driver that is being used - @type driver: L{AzureStorageDriver} + :param driver: The Azure storage driver that is being used + :type driver: :class:`AzureStorageDriver` - @param object_path: The path of the object we need to lease - @type object_path: C{str} + :param object_path: The path of the object we need to lease + :type object_path: ``str`` - @param use_lease: Indicates if we must take a lease or not - @type use_lease: C{bool} + :param use_lease: Indicates if we must take a lease or not + :type use_lease: ``bool`` """ self.object_path = object_path self.driver = driver @@ -200,11 +200,11 @@ class AzureBlobsStorageDriver(StorageDriver): """ Converts a container XML node to a container instance - @param node: XML info of the container - @type node: L{xml.etree.ElementTree.Element} + :param node: XML info of the container + :type node: :class:`xml.etree.ElementTree.Element` - @return: A container instance - @rtype: L{Container} + :return: A container instance + :rtype: :class:`Container` """ name = node.findtext(fixxpath(xpath='Name')) @@ -232,14 +232,14 @@ class AzureBlobsStorageDriver(StorageDriver): """ Converts a HTTP response to a container instance - @param container_name: Name of the container - @type container_name: C{str} + :param container_name: Name of the container + :type container_name: ``str`` - @param response: HTTP Response - @type node: L{} + :param response: HTTP Response + :type node: L{} - @return: A container instance - @rtype: L{Container} + :return: A container instance + :rtype: :class:`Container` """ headers = response.headers @@ -267,14 +267,14 @@ class AzureBlobsStorageDriver(StorageDriver): """ Converts a BLOB XML node to an object instance - @param container: Instance of the container holding the blob - @type: L{Container} + :param container: Instance of the container holding the blob + :type: :class:`Container` - @param blob: XML info of the blob - @type blob: L{} + :param blob: XML info of the blob + :type blob: L{} - @return: An object instance - @rtype: L{Object} + :return: An object instance + :rtype: :class:`Object` """ name = blob.findtext(fixxpath(xpath='Name')) @@ -318,17 +318,17 @@ class AzureBlobsStorageDriver(StorageDriver): """ Converts a HTTP response to an object (from headers) - @param object_name: Name of the object - @type object_name: C{str} + :param object_name: Name of the object + :type object_name: ``str`` - @param container: Instance of the container holding the blob - @type: L{Container} + :param container: Instance of the container holding the blob + :type: :class:`Container` - @param response: HTTP Response - @type node: L{} + :param response: HTTP Response + :type node: L{} - @return: An object instance - @rtype: L{Object} + :return: An object instance + :rtype: :class:`Object` """ headers = response.headers @@ -368,7 +368,7 @@ class AzureBlobsStorageDriver(StorageDriver): def iterate_containers(self): """ - @inherits: L{StorageDriver.iterate_containers} + @inherits: :class:`StorageDriver.iterate_containers` """ params = {'comp': 'list', 'maxresults': RESPONSES_PER_REQUEST, @@ -393,7 +393,7 @@ class AzureBlobsStorageDriver(StorageDriver): def iterate_container_objects(self, container): """ - @inherits: L{StorageDriver.iterate_container_objects} + @inherits: :class:`StorageDriver.iterate_container_objects` """ params = {'restype': 'container', 'comp': 'list', @@ -428,7 +428,7 @@ class AzureBlobsStorageDriver(StorageDriver): def get_container(self, container_name): """ - @inherits: L{StorageDriver.get_container} + @inherits: :class:`StorageDriver.get_container` """ params = {'restype': 'container'} @@ -449,7 +449,7 @@ class AzureBlobsStorageDriver(StorageDriver): def get_object(self, container_name, object_name): """ - @inherits: L{StorageDriver.get_object} + @inherits: :class:`StorageDriver.get_object` """ container = self.get_container(container_name=container_name) @@ -468,11 +468,11 @@ class AzureBlobsStorageDriver(StorageDriver): """ Return a container path - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @return: A path for this container. - @rtype: C{str} + :return: A path for this container. + :rtype: ``str`` """ return '/%s' % (container.name) @@ -480,14 +480,14 @@ class AzureBlobsStorageDriver(StorageDriver): """ Return an object's CDN path. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @param object_name: Object name - @type object_name: L{str} + :param object_name: Object name + :type object_name: :class:`str` - @return: A path for this object. - @rtype: C{str} + :return: A path for this object. + :rtype: ``str`` """ container_url = self._get_container_path(container) object_name_cleaned = urlquote(object_name) @@ -496,7 +496,7 @@ class AzureBlobsStorageDriver(StorageDriver): def create_container(self, container_name): """ - @inherits: L{StorageDriver.create_container} + @inherits: :class:`StorageDriver.create_container` """ params = {'restype': 'container'} @@ -522,7 +522,7 @@ class AzureBlobsStorageDriver(StorageDriver): def delete_container(self, container): """ - @inherits: L{StorageDriver.delete_container} + @inherits: :class:`StorageDriver.delete_container` """ # Azure does not check if the container is empty. So, we will do # a check to ensure that the behaviour is similar to other drivers @@ -550,7 +550,7 @@ class AzureBlobsStorageDriver(StorageDriver): def download_object(self, obj, destination_path, overwrite_existing=False, delete_on_failure=True): """ - @inherits: L{StorageDriver.download_object} + @inherits: :class:`StorageDriver.download_object` """ obj_path = self._get_object_path(obj.container, obj.name) response = self.connection.request(obj_path, raw=True, data=None) @@ -567,7 +567,7 @@ class AzureBlobsStorageDriver(StorageDriver): def download_object_as_stream(self, obj, chunk_size=None): """ - @inherits: L{StorageDriver.download_object_as_stream} + @inherits: :class:`StorageDriver.download_object_as_stream` """ obj_path = self._get_object_path(obj.container, obj.name) response = self.connection.request(obj_path, raw=True, data=None) @@ -583,29 +583,29 @@ class AzureBlobsStorageDriver(StorageDriver): """ Uploads data from an interator in fixed sized chunks to S3 - @param response: Response object from the initial POST request - @type response: L{RawResponse} + :param response: Response object from the initial POST request + :type response: :class:`RawResponse` - @param data: Any data from the initial POST request - @type data: C{str} + :param data: Any data from the initial POST request + :type data: ``str`` - @param iterator: The generator for fetching the upload data - @type iterator: C{generator} + :param iterator: The generator for fetching the upload data + :type iterator: ``generator`` - @param object_path: The path of the object to which we are uploading - @type object_name: C{str} + :param object_path: The path of the object to which we are uploading + :type object_name: ``str`` - @param blob_type: The blob type being uploaded - @type blob_type: C{str} + :param blob_type: The blob type being uploaded + :type blob_type: ``str`` - @param lease: The lease object to be used for renewal - @type lease: L{AzureBlobLease} + :param lease: The lease object to be used for renewal + :type lease: :class:`AzureBlobLease` - @keyword calculate_hash: Indicates if we must calculate the data hash - @type calculate_hash: C{bool} + :keyword calculate_hash: Indicates if we must calculate the data hash + :type calculate_hash: ``bool`` - @return: A tuple of (status, checksum, bytes transferred) - @rtype: C{tuple} + :return: A tuple of (status, checksum, bytes transferred) + :rtype: ``tuple`` """ # Get the upload id from the response xml @@ -691,11 +691,11 @@ class AzureBlobsStorageDriver(StorageDriver): """ Makes a final commit of the data. - @param object_path: Server side object path. - @type object_path: C{str} + :param object_path: Server side object path. + :type object_path: ``str`` - @param upload_id: A list of (chunk_number, chunk_hash) tuples. - @type upload_id: C{list} + :param upload_id: A list of (chunk_number, chunk_hash) tuples. + :type upload_id: ``list`` """ root = Element('BlockList') @@ -722,11 +722,11 @@ class AzureBlobsStorageDriver(StorageDriver): """ Checks if extension arguments are valid - @param blob_type: The blob type that is being uploaded - @type blob_type: C{str} + :param blob_type: The blob type that is being uploaded + :type blob_type: ``str`` - @param object_size: The (max) size of the object being uploaded - @type object_size: C{int} + :param object_size: The (max) size of the object being uploaded + :type object_size: ``int`` """ if blob_type not in ['BlockBlob', 'PageBlob']: @@ -746,13 +746,13 @@ class AzureBlobsStorageDriver(StorageDriver): """ Upload an object currently located on a disk. - @inherits: L{StorageDriver.upload_object} + @inherits: :class:`StorageDriver.upload_object` - @param ex_blob_type: Storage class - @type ex_blob_type: C{str} + :param ex_blob_type: Storage class + :type ex_blob_type: ``str`` - @param ex_use_lease: Indicates if we must take a lease before upload - @type ex_use_lease: C{bool} + :param ex_use_lease: Indicates if we must take a lease before upload + :type ex_use_lease: ``bool`` """ if ex_blob_type is None: @@ -804,17 +804,17 @@ class AzureBlobsStorageDriver(StorageDriver): ex_use_lease=False, ex_blob_type=None, ex_page_blob_size=None): """ - @inherits: L{StorageDriver.upload_object_via_stream} + @inherits: :class:`StorageDriver.upload_object_via_stream` - @param ex_blob_type: Storage class - @type ex_blob_type: C{str} + :param ex_blob_type: Storage class + :type ex_blob_type: ``str`` - @param ex_page_blob_size: The maximum size to which the + :param ex_page_blob_size: The maximum size to which the page blob can grow to - @type ex_page_blob_size: C{int} + :type ex_page_blob_size: ``int`` - @param ex_use_lease: Indicates if we must take a lease before upload - @type ex_use_lease: C{bool} + :param ex_use_lease: Indicates if we must take a lease before upload + :type ex_use_lease: ``bool`` """ if ex_blob_type is None: @@ -841,7 +841,7 @@ class AzureBlobsStorageDriver(StorageDriver): def delete_object(self, obj): """ - @inherits: L{StorageDriver.delete_object} + @inherits: :class:`StorageDriver.delete_object` """ object_path = self._get_object_path(obj.container, obj.name) response = self.connection.request(object_path, method='DELETE') @@ -858,11 +858,11 @@ class AzureBlobsStorageDriver(StorageDriver): """ Update the given metadata in the headers - @param headers: The headers dictionary to be updated - @type headers: C{dict} + :param headers: The headers dictionary to be updated + :type headers: ``dict`` - @param meta_data: Metadata key value pairs - @type meta_data: C{dict} + :param meta_data: Metadata key value pairs + :type meta_data: ``dict`` """ for key, value in list(meta_data.items()): key = 'x-ms-meta-%s' % (key) @@ -873,21 +873,21 @@ class AzureBlobsStorageDriver(StorageDriver): """ Prepare headers for uploading an object - @param object_name: The full name of the object being updated - @type object_name: C{str} + :param object_name: The full name of the object being updated + :type object_name: ``str`` - @param object_size: The size of the object. In case of PageBlobs, + :param object_size: The size of the object. In case of PageBlobs, this indicates the maximum size the blob can grow to - @type object_size: C{int} + :type object_size: ``int`` - @param extra: Extra control data for the upload - @type extra: C{dict} + :param extra: Extra control data for the upload + :type extra: ``dict`` - @param meta_data: Metadata key value pairs - @type meta_data: C{dict} + :param meta_data: Metadata key value pairs + :type meta_data: ``dict`` - @param blob_type: Page or Block blob type - @type blob_type: C{str} + :param blob_type: Page or Block blob type + :type blob_type: ``str`` """ headers = {} @@ -971,11 +971,11 @@ class AzureBlobsStorageDriver(StorageDriver): """ Set metadata for an object - @param obj: The blob object - @type obj: L{Object} + :param obj: The blob object + :type obj: :class:`Object` - @param meta_data: Metadata key value pairs - @type meta_data: C{dict} + :param meta_data: Metadata key value pairs + :type meta_data: ``dict`` """ object_path = self._get_object_path(obj.container, obj.name) params = {'comp': 'metadata'} http://git-wip-us.apache.org/repos/asf/libcloud/blob/f01e0637/libcloud/storage/drivers/cloudfiles.py ---------------------------------------------------------------------- diff --git a/libcloud/storage/drivers/cloudfiles.py b/libcloud/storage/drivers/cloudfiles.py index 7f0cafa..6fd54d4 100644 --- a/libcloud/storage/drivers/cloudfiles.py +++ b/libcloud/storage/drivers/cloudfiles.py @@ -206,10 +206,10 @@ class CloudFilesStorageDriver(StorageDriver, OpenStackDriverMixin): def __init__(self, key, secret=None, secure=True, host=None, port=None, region='ord', **kwargs): """ - @inherits: L{StorageDriver.__init__} + @inherits: :class:`StorageDriver.__init__` - @param region: ID of the region which should be used. - @type region: C{str} + :param region: ID of the region which should be used. + :type region: ``str`` """ if hasattr(self, '_region'): region = self._region @@ -288,10 +288,10 @@ class CloudFilesStorageDriver(StorageDriver, OpenStackDriverMixin): def enable_container_cdn(self, container, ex_ttl=None): """ - @inherits: L{StorageDriver.enable_container_cdn} + @inherits: :class:`StorageDriver.enable_container_cdn` - @param ex_ttl: cache time to live - @type ex_ttl: C{int} + :param ex_ttl: cache time to live + :type ex_ttl: ``int`` """ container_name = container.name headers = {'X-CDN-Enabled': 'True'} @@ -419,9 +419,9 @@ class CloudFilesStorageDriver(StorageDriver, OpenStackDriverMixin): """ Purge edge cache for the specified object. - @param email: Email where a notification will be sent when the job + :param email: Email where a notification will be sent when the job completes. (optional) - @type email: C{str} + :type email: ``str`` """ container_name = self._encode_container_name(obj.container.name) object_name = self._encode_object_name(obj.name) @@ -439,7 +439,7 @@ class CloudFilesStorageDriver(StorageDriver, OpenStackDriverMixin): """ Get meta data - @rtype: C{dict} + :rtype: ``dict`` """ response = self.connection.request('', method='HEAD') @@ -486,14 +486,14 @@ class CloudFilesStorageDriver(StorageDriver, OpenStackDriverMixin): """ Enable serving a static website. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @param index_file: Name of the object which becomes an index page for + :param index_file: Name of the object which becomes an index page for every sub-directory in this container. - @type index_file: C{str} + :type index_file: ``str`` - @rtype: C{bool} + :rtype: ``bool`` """ container_name = container.name headers = {'X-Container-Meta-Web-Index': index_file} @@ -510,13 +510,13 @@ class CloudFilesStorageDriver(StorageDriver, OpenStackDriverMixin): Set a custom error page which is displayed if file is not found and serving of a static website is enabled. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @param file_name: Name of the object which becomes the error page. - @type file_name: C{str} + :param file_name: Name of the object which becomes the error page. + :type file_name: ``str`` - @rtype: C{bool} + :rtype: ``bool`` """ container_name = container.name headers = {'X-Container-Meta-Web-Error': file_name} @@ -533,10 +533,10 @@ class CloudFilesStorageDriver(StorageDriver, OpenStackDriverMixin): Set the metadata header X-Account-Meta-Temp-URL-Key on your Cloud Files account. - @param key: X-Account-Meta-Temp-URL-Key - @type key: C{str} + :param key: X-Account-Meta-Temp-URL-Key + :type key: ``str`` - @rtype: C{bool} + :rtype: ``bool`` """ headers = {'X-Account-Meta-Temp-URL-Key': key} @@ -555,17 +555,17 @@ class CloudFilesStorageDriver(StorageDriver, OpenStackDriverMixin): wish. This method is specifically for allowing users to retrieve or update an object. - @param obj: The object that you wish to make temporarily public - @type obj: L{Object} + :param obj: The object that you wish to make temporarily public + :type obj: :class:`Object` - @param method: Which method you would like to allow, 'PUT' or 'GET' - @type method: C{str} + :param method: Which method you would like to allow, 'PUT' or 'GET' + :type method: ``str`` - @param timeout: Time (in seconds) after which you want the TempURL + :param timeout: Time (in seconds) after which you want the TempURL to expire. - @type timeout: C{int} + :type timeout: ``int`` - @rtype: C{bool} + :rtype: ``bool`` """ self.connection._populate_hosts_and_request_paths() expires = int(time() + timeout) http://git-wip-us.apache.org/repos/asf/libcloud/blob/f01e0637/libcloud/storage/drivers/dummy.py ---------------------------------------------------------------------- diff --git a/libcloud/storage/drivers/dummy.py b/libcloud/storage/drivers/dummy.py index 145e5e6..8e4539a 100644 --- a/libcloud/storage/drivers/dummy.py +++ b/libcloud/storage/drivers/dummy.py @@ -96,11 +96,11 @@ class DummyStorageDriver(StorageDriver): def __init__(self, api_key, api_secret): """ - @param api_key: API key or username to used (required) - @type api_key: C{str} - @param api_secret: Secret password to be used (required) - @type api_secret: C{str} - @rtype: C{None} + :param api_key: API key or username to used (required) + :type api_key: ``str`` + :param api_secret: Secret password to be used (required) + :type api_secret: ``str`` + :rtype: ``None`` """ self._containers = {} @@ -124,7 +124,7 @@ class DummyStorageDriver(StorageDriver): >>> driver.get_meta_data()['bytes_used'] 50 - @rtype: C{dict} + :rtype: ``dict`` """ container_count = len(self._containers) @@ -162,7 +162,7 @@ class DummyStorageDriver(StorageDriver): >>> sorted([container.name for container in container_list]) ['test container 1', 'test container 2'] - @inherits: L{StorageDriver.iterate_containers} + @inherits: :class:`StorageDriver.iterate_containers` """ for container in list(self._containers.values()): @@ -187,7 +187,7 @@ class DummyStorageDriver(StorageDriver): >>> driver.get_container('test container 1') <Container: name=test container 1, provider=Dummy Storage Provider> - @inherits: L{StorageDriver.get_container} + @inherits: :class:`StorageDriver.get_container` """ if container_name not in self._containers: @@ -210,7 +210,7 @@ class DummyStorageDriver(StorageDriver): >>> container.get_cdn_url() 'http://www.test.com/container/test_container_1' - @inherits: L{StorageDriver.get_container_cdn_url} + @inherits: :class:`StorageDriver.get_container_cdn_url` """ if container.name not in self._containers: @@ -237,7 +237,7 @@ class DummyStorageDriver(StorageDriver): >>> obj <Object: name=test object, size=50, hash=None, provider=Dummy Storage Provider ...> - @inherits: L{StorageDriver.get_object} + @inherits: :class:`StorageDriver.get_object` """ self.get_container(container_name) @@ -261,7 +261,7 @@ class DummyStorageDriver(StorageDriver): >>> obj.get_cdn_url() 'http://www.test.com/object/test_object_5' - @inherits: L{StorageDriver.get_object_cdn_url} + @inherits: :class:`StorageDriver.get_object_cdn_url` """ container_name = obj.container.name @@ -283,7 +283,7 @@ class DummyStorageDriver(StorageDriver): Traceback (most recent call last): ContainerAlreadyExistsError: - @inherits: L{StorageDriver.create_container} + @inherits: :class:`StorageDriver.create_container` """ if container_name in self._containers: @@ -325,7 +325,7 @@ class DummyStorageDriver(StorageDriver): Traceback (most recent call last): ContainerIsNotEmptyError: - @inherits: L{StorageDriver.delete_container} + @inherits: :class:`StorageDriver.delete_container` """ container_name = container.name @@ -362,7 +362,7 @@ class DummyStorageDriver(StorageDriver): >>> stream #doctest: +ELLIPSIS <...closed...> - @inherits: L{StorageDriver.download_object_as_stream} + @inherits: :class:`StorageDriver.download_object_as_stream` """ return DummyFileObject() @@ -384,9 +384,9 @@ class DummyStorageDriver(StorageDriver): >>> obj.size == file_size True - @inherits: L{StorageDriver.upload_object} - @param file_hash: File hash - @type file_hash: C{str} + @inherits: :class:`StorageDriver.upload_object` + :param file_hash: File hash + :type file_hash: ``str`` """ if not os.path.exists(file_path): @@ -408,7 +408,7 @@ class DummyStorageDriver(StorageDriver): >>> obj #doctest: +ELLIPSIS <Object: name=test object, size=50, ...> - @inherits: L{StorageDriver.upload_object_via_stream} + @inherits: :class:`StorageDriver.upload_object_via_stream` """ size = len(iterator) @@ -433,7 +433,7 @@ class DummyStorageDriver(StorageDriver): Traceback (most recent call last): ObjectDoesNotExistError: - @inherits: L{StorageDriver.delete_object} + @inherits: :class:`StorageDriver.delete_object` """ container_name = obj.container.name http://git-wip-us.apache.org/repos/asf/libcloud/blob/f01e0637/libcloud/storage/drivers/local.py ---------------------------------------------------------------------- diff --git a/libcloud/storage/drivers/local.py b/libcloud/storage/drivers/local.py index 77ddb23..b8c20a1 100644 --- a/libcloud/storage/drivers/local.py +++ b/libcloud/storage/drivers/local.py @@ -109,8 +109,8 @@ class LocalStorageDriver(StorageDriver): """ Check if the container name is valid - @param container_name: Container name - @type container_name: C{str} + :param container_name: Container name + :type container_name: ``str`` """ if '/' in container_name or '\\' in container_name: @@ -121,11 +121,11 @@ class LocalStorageDriver(StorageDriver): """ Create a container instance - @param container_name: Container name. - @type container_name: C{str} + :param container_name: Container name. + :type container_name: ``str`` - @return: Container instance. - @rtype: L{Container} + :return: Container instance. + :rtype: :class:`Container` """ self._check_container_name(container_name) @@ -151,14 +151,14 @@ class LocalStorageDriver(StorageDriver): """ Create an object instance - @param container: Container. - @type container: L{Container} + :param container: Container. + :type container: :class:`Container` - @param object_name: Object name. - @type object_name: C{str} + :param object_name: Object name. + :type object_name: ``str`` - @return: Object instance. - @rtype: L{Object} + :return: Object instance. + :rtype: :class:`Object` """ full_path = os.path.join(self.base_path, container.name, object_name) @@ -192,8 +192,8 @@ class LocalStorageDriver(StorageDriver): """ Return a generator of containers. - @return: A generator of Container instances. - @rtype: C{generator} of L{Container} + :return: A generator of Container instances. + :rtype: ``generator`` of :class:`Container` """ for container_name in os.listdir(self.base_path): @@ -224,11 +224,11 @@ class LocalStorageDriver(StorageDriver): """ Returns 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` """ return self._get_objects(container) @@ -237,11 +237,11 @@ class LocalStorageDriver(StorageDriver): """ 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` """ return self._make_container(container_name) @@ -249,14 +249,14 @@ class LocalStorageDriver(StorageDriver): """ Return a container CDN URL. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @param check: Indicates if the path's existance must be checked - @type check: C{bool} + :param check: Indicates if the path's existance must be checked + :type check: ``bool`` - @return: A CDN URL for this container. - @rtype: C{str} + :return: A CDN URL for this container. + :rtype: ``str`` """ path = os.path.join(self.base_path, container.name) @@ -270,14 +270,14 @@ class LocalStorageDriver(StorageDriver): """ 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` """ container = self._make_container(container_name) return self._make_object(container, object_name) @@ -286,11 +286,11 @@ class LocalStorageDriver(StorageDriver): """ 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`` """ return os.path.join(self.base_path, obj.container.name, obj.name) @@ -298,10 +298,10 @@ class LocalStorageDriver(StorageDriver): """ Enable container CDN. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @rtype: C{bool} + :rtype: ``bool`` """ path = self.get_container_cdn_url(container) @@ -316,10 +316,10 @@ class LocalStorageDriver(StorageDriver): """ Enable object CDN. - @param obj: Object instance - @type obj: L{Object} + :param obj: Object instance + :type obj: :class:`Object` - @rtype: C{bool} + :rtype: ``bool`` """ path = self.get_object_cdn_url(obj) @@ -339,24 +339,24 @@ class LocalStorageDriver(StorageDriver): """ 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 + :param destination_path: Full path to a file or a directory where the incoming file will be saved. - @type destination_path: C{str} + :type destination_path: ``str`` - @param overwrite_existing: True to overwrite an existing file, + :param overwrite_existing: True to overwrite an existing file, defaults to False. - @type overwrite_existing: C{bool} + :type overwrite_existing: ``bool`` - @param delete_on_failure: True to delete a partially downloaded file if + :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} + :type delete_on_failure: ``bool`` - @return: True if an object has been successfully downloaded, False + :return: True if an object has been successfully downloaded, False otherwise. - @rtype: C{bool} + :rtype: ``bool`` """ obj_path = self.get_object_cdn_url(obj) @@ -394,13 +394,13 @@ class LocalStorageDriver(StorageDriver): """ 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} + :param chunk_size: Optional chunk size (in bytes). + :type chunk_size: ``int`` - @rtype: C{object} + :rtype: ``object`` """ path = self.get_object_cdn_url(obj) @@ -414,22 +414,22 @@ class LocalStorageDriver(StorageDriver): """ 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 hast - @type verify_hash: C{bool} + :param verify_hash: Verify hast + :type verify_hash: ``bool`` - @param extra: (optional) Extra attributes (driver specific). - @type extra: C{dict} + :param extra: (optional) Extra attributes (driver specific). + :type extra: ``dict`` - @rtype: C{object} + :rtype: ``object`` """ path = self.get_container_cdn_url(container, check=True) @@ -465,21 +465,21 @@ class LocalStorageDriver(StorageDriver): 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: ``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: ``object`` """ path = self.get_container_cdn_url(container, check=True) @@ -503,11 +503,11 @@ class LocalStorageDriver(StorageDriver): """ 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`` """ path = self.get_object_cdn_url(obj) @@ -540,11 +540,11 @@ class LocalStorageDriver(StorageDriver): """ 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: :class:`Container` instance on success. + :rtype: :class:`Container` """ self._check_container_name(container_name) @@ -575,11 +575,11 @@ class LocalStorageDriver(StorageDriver): """ 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`` """ # Check if there are any objects inside this http://git-wip-us.apache.org/repos/asf/libcloud/blob/f01e0637/libcloud/storage/drivers/s3.py ---------------------------------------------------------------------- diff --git a/libcloud/storage/drivers/s3.py b/libcloud/storage/drivers/s3.py index 0b54297..c1cf3c0 100644 --- a/libcloud/storage/drivers/s3.py +++ b/libcloud/storage/drivers/s3.py @@ -182,20 +182,20 @@ class S3MultipartUpload(object): """ Class representing an amazon s3 multipart upload - @param key: The object/key that was being uploaded - @type key: C{str} + :param key: The object/key that was being uploaded + :type key: ``str`` - @param id: The upload id assigned by amazon - @type id: C{str} + :param id: The upload id assigned by amazon + :type id: ``str`` - @param created_at: The date/time at which the upload was started - @type created_at: C{str} + :param created_at: The date/time at which the upload was started + :type created_at: ``str`` - @param initiator: The AWS owner/IAM user who initiated this - @type initiator: C{str} + :param initiator: The AWS owner/IAM user who initiated this + :type initiator: ``str`` - @param owner: The AWS owner/IAM who will own this object - @type owner: C{str} + :param owner: The AWS owner/IAM who will own this object + :type owner: ``str`` """ self.key = key self.id = id @@ -316,11 +316,11 @@ class S3StorageDriver(StorageDriver): """ Return a container path - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @return: A path for this container. - @rtype: C{str} + :return: A path for this container. + :rtype: ``str`` """ return '/%s' % (container.name) @@ -328,14 +328,14 @@ class S3StorageDriver(StorageDriver): """ Return an object's CDN path. - @param container: Container instance - @type container: L{Container} + :param container: Container instance + :type container: :class:`Container` - @param object_name: Object name - @type object_name: L{str} + :param object_name: Object name + :type object_name: :class:`str` - @return: A path for this object. - @rtype: C{str} + :return: A path for this object. + :rtype: ``str`` """ container_url = self._get_container_path(container) object_name_cleaned = self._clean_object_name(object_name) @@ -419,10 +419,10 @@ class S3StorageDriver(StorageDriver): def upload_object(self, file_path, container, object_name, extra=None, verify_hash=True, ex_storage_class=None): """ - @inherits: L{StorageDriver.upload_object} + @inherits: :class:`StorageDriver.upload_object` - @param ex_storage_class: Storage class - @type ex_storage_class: C{str} + :param ex_storage_class: Storage class + :type ex_storage_class: ``str`` """ upload_func = self._upload_file upload_func_kwargs = {'file_path': file_path} @@ -440,27 +440,27 @@ class S3StorageDriver(StorageDriver): Callback invoked for uploading data to S3 using Amazon's multipart upload mechanism - @param response: Response object from the initial POST request - @type response: L{S3RawResponse} + :param response: Response object from the initial POST request + :type response: :class:`S3RawResponse` - @param data: Any data from the initial POST request - @type data: C{str} + :param data: Any data from the initial POST request + :type data: ``str`` - @param iterator: The generator for fetching the upload data - @type iterator: C{generator} + :param iterator: The generator for fetching the upload data + :type iterator: ``generator`` - @param container: The container owning the object to which data is + :param container: The container owning the object to which data is being uploaded - @type container: L{Container} + :type container: :class:`Container` - @param object_name: The name of the object to which we are uploading - @type object_name: C{str} + :param object_name: The name of the object to which we are uploading + :type object_name: ``str`` - @keyword calculate_hash: Indicates if we must calculate the data hash - @type calculate_hash: C{bool} + :keyword calculate_hash: Indicates if we must calculate the data hash + :type calculate_hash: ``bool`` - @return: A tuple of (status, checksum, bytes transferred) - @rtype: C{tuple} + :return: A tuple of (status, checksum, bytes transferred) + :rtype: ``tuple`` """ object_path = self._get_object_path(container, object_name) @@ -496,20 +496,20 @@ class S3StorageDriver(StorageDriver): """ Uploads data from an interator in fixed sized chunks to S3 - @param iterator: The generator for fetching the upload data - @type iterator: C{generator} + :param iterator: The generator for fetching the upload data + :type iterator: ``generator`` - @param object_path: The path of the object to which we are uploading - @type object_name: C{str} + :param object_path: The path of the object to which we are uploading + :type object_name: ``str`` - @param upload_id: The upload id allocated for this multipart upload - @type upload_id: C{str} + :param upload_id: The upload id allocated for this multipart upload + :type upload_id: ``str`` - @keyword calculate_hash: Indicates if we must calculate the data hash - @type calculate_hash: C{bool} + :keyword calculate_hash: Indicates if we must calculate the data hash + :type calculate_hash: ``bool`` - @return: A tuple of (chunk info, checksum, bytes transferred) - @rtype: C{tuple} + :return: A tuple of (chunk info, checksum, bytes transferred) + :rtype: ``tuple`` """ data_hash = None @@ -561,14 +561,14 @@ class S3StorageDriver(StorageDriver): """ Makes a final commit of the data. - @param object_path: Server side object path. - @type object_path: C{str} + :param object_path: Server side object path. + :type object_path: ``str`` - @param upload_id: ID of the multipart upload. - @type upload_id: C{str} + :param upload_id: ID of the multipart upload. + :type upload_id: ``str`` - @param upload_id: A list of (chunk_number, chunk_hash) tuples. - @type upload_id: C{list} + :param upload_id: A list of (chunk_number, chunk_hash) tuples. + :type upload_id: ``list`` """ root = Element('CompleteMultipartUpload') @@ -601,11 +601,11 @@ class S3StorageDriver(StorageDriver): """ Aborts an already initiated multipart upload - @param object_path: Server side object path. - @type object_path: C{str} + :param object_path: Server side object path. + :type object_path: ``str`` - @param upload_id: ID of the multipart upload. - @type upload_id: C{str} + :param upload_id: ID of the multipart upload. + :type upload_id: ``str`` """ params = {'uploadId': upload_id} @@ -619,10 +619,10 @@ class S3StorageDriver(StorageDriver): def upload_object_via_stream(self, iterator, container, object_name, extra=None, ex_storage_class=None): """ - @inherits: L{StorageDriver.upload_object_via_stream} + @inherits: :class:`StorageDriver.upload_object_via_stream` - @param ex_storage_class: Storage class - @type ex_storage_class: C{str} + :param ex_storage_class: Storage class + :type ex_storage_class: ``str`` """ method = 'PUT' @@ -676,18 +676,18 @@ class S3StorageDriver(StorageDriver): Each multipart upload which has not been committed or aborted is considered in-progress. - @param container: The container holding the uploads - @type container: L{Container} + :param container: The container holding the uploads + :type container: :class:`Container` - @keyword prefix: Print only uploads of objects with this prefix - @type prefix: C{str} + :keyword prefix: Print only uploads of objects with this prefix + :type prefix: ``str`` - @keyword delimiter: The object/key names are grouped based on + :keyword delimiter: The object/key names are grouped based on being split by this delimiter - @type delimiter: C{str} + :type delimiter: ``str`` - @return: A generator of S3MultipartUpload instances. - @rtype: C{generator} of L{S3MultipartUpload} + :return: A generator of S3MultipartUpload instances. + :rtype: ``generator`` of :class:`S3MultipartUpload` """ if not self.supports_s3_multipart_upload: @@ -753,11 +753,11 @@ class S3StorageDriver(StorageDriver): Extension method for removing all partially completed S3 multipart uploads. - @param container: The container holding the uploads - @type container: L{Container} + :param container: The container holding the uploads + :type container: :class:`Container` - @keyword prefix: Delete only uploads of objects with this prefix - @type prefix: C{str} + :keyword prefix: Delete only uploads of objects with this prefix + :type prefix: ``str`` """ # Iterate through the container and delete the upload ids http://git-wip-us.apache.org/repos/asf/libcloud/blob/f01e0637/libcloud/storage/types.py ---------------------------------------------------------------------- diff --git a/libcloud/storage/types.py b/libcloud/storage/types.py index 8301b92..bc2d0bf 100644 --- a/libcloud/storage/types.py +++ b/libcloud/storage/types.py @@ -30,19 +30,19 @@ class Provider(object): """ Defines for each of the supported providers - @cvar DUMMY: Example provider - @cvar CLOUDFILES_US: CloudFiles US - @cvar CLOUDFILES_UK: CloudFiles UK - @cvar S3: Amazon S3 US - @cvar S3_US_WEST: Amazon S3 US West (Northern California) - @cvar S3_EU_WEST: Amazon S3 EU West (Ireland) - @cvar S3_AP_SOUTHEAST_HOST: Amazon S3 Asia South East (Singapore) - @cvar S3_AP_NORTHEAST_HOST: Amazon S3 Asia South East (Tokyo) - @cvar NINEFOLD: Ninefold - @cvar GOOGLE_STORAGE Google Storage - @cvar S3_US_WEST_OREGON: Amazon S3 US West 2 (Oregon) - @cvar NIMBUS: Nimbus.io driver - @cvar LOCAL: Local storage driver + :cvar DUMMY: Example provider + :cvar CLOUDFILES_US: CloudFiles US + :cvar CLOUDFILES_UK: CloudFiles UK + :cvar S3: Amazon S3 US + :cvar S3_US_WEST: Amazon S3 US West (Northern California) + :cvar S3_EU_WEST: Amazon S3 EU West (Ireland) + :cvar S3_AP_SOUTHEAST_HOST: Amazon S3 Asia South East (Singapore) + :cvar S3_AP_NORTHEAST_HOST: Amazon S3 Asia South East (Tokyo) + :cvar NINEFOLD: Ninefold + :cvar GOOGLE_STORAGE Google Storage + :cvar S3_US_WEST_OREGON: Amazon S3 US West 2 (Oregon) + :cvar NIMBUS: Nimbus.io driver + :cvar LOCAL: Local storage driver """ DUMMY = 'dummy' S3 = 's3' http://git-wip-us.apache.org/repos/asf/libcloud/blob/f01e0637/libcloud/utils/files.py ---------------------------------------------------------------------- diff --git a/libcloud/utils/files.py b/libcloud/utils/files.py index b968b2f..201e94a 100644 --- a/libcloud/utils/files.py +++ b/libcloud/utils/files.py @@ -31,15 +31,15 @@ def read_in_chunks(iterator, chunk_size=None, fill_size=False): """ Return a generator which yields data in chunks. - @type iterator: C{Iterator} - @param response: An object which implements an iterator interface + :type iterator: :class:`object` which implements iterator interface. + :param response: An object which implements an iterator interface or a File like object with read method. - @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) - @type fill_size: C{bool} - @param fill_size: If True, make sure chunks are chunk_size in length + :type fill_size: ``bool`` + :param fill_size: If True, make sure chunks are chunk_size in length (except for last chunk). TODO: At some point in the future we could use byte arrays here if version @@ -84,12 +84,12 @@ def exhaust_iterator(iterator): """ Exhaust an iterator and return all data returned by it. - @type iterator: C{Iterator} - @param response: An object which implements an iterator interface + :type iterator: :class:`object` which implements iterator interface. + :param response: An object which implements an iterator interface or a File like object with read method. - @rtype C{str} - @return Data returned by the iterator. + :rtype ``str`` + :return Data returned by the iterator. """ data = b('') http://git-wip-us.apache.org/repos/asf/libcloud/blob/f01e0637/libcloud/utils/misc.py ---------------------------------------------------------------------- diff --git a/libcloud/utils/misc.py b/libcloud/utils/misc.py index bfd9a92..93570ad 100644 --- a/libcloud/utils/misc.py +++ b/libcloud/utils/misc.py @@ -31,9 +31,9 @@ def get_driver(drivers, provider): """ Get a driver. - @param drivers: Dictionary containing valid providers. - @param provider: Id of provider to get driver - @type provider: L{libcloud.types.Provider} + :param drivers: Dictionary containing valid providers. + :param provider: Id of provider to get driver + :type provider: :class:`libcloud.types.Provider` """ if provider in drivers: mod_name, driver_name = drivers[provider] @@ -47,13 +47,13 @@ def set_driver(drivers, provider, module, klass): """ Sets a driver. - @param drivers: Dictionary to store providers. - @param provider: Id of provider to set driver for - @type provider: L{libcloud.types.Provider} - @param module: The module which contains the driver - @type module: L - @param klass: The driver class name - @type klass: + :param drivers: Dictionary to store providers. + :param provider: Id of provider to set driver for + :type provider: :class:`libcloud.types.Provider` + :param module: The module which contains the driver + :type module: L + :param klass: The driver class name + :type klass: """ if provider in drivers:
