[storage-blob] Docs updates (#6184)

* Docs updates

* Some docstring fixes

sdk/storage/azure-storage-blob/HISTORY.md

@@ -1,10 +1,21 @@
 # Change Log azure-storage-blob
 
-> See [BreakingChanges](BreakingChanges.md) for a detailed list of API breaks.
+## Version 12.0.0b1:
 
-## Version 12.0.0:
+For release notes and more information please visit
+https://aka.ms/azure-sdk-preview1-python
 
-- New API.
+## Version 2.0.1:
+
+- Updated dependency on azure-storage-common.
+
+## Version 2.0.0:
+
+- Support for 2018-11-09 REST version. Please see our REST API documentation and blog for information about the related added features.
+- Added support for append block from URL(synchronously) for append blobs.
+- Added support for update page from URL(synchronously) for page blobs.
+- Added support for generating and using blob snapshot SAS tokens.
+- Added support for generating user delegation SAS tokens.
 
 ## Version 1.5.0:
 

sdk/storage/azure-storage-blob/azure/storage/blob/__init__.py

@@ -12,13 +12,15 @@
 from .container_client import ContainerClient
 from .blob_service_client import BlobServiceClient
 from .lease import LeaseClient
+from .polling import CopyStatusPoller
 from ._shared.policies import ExponentialRetry, LinearRetry, NoRetry
 from ._shared.models import(
     LocationMode,
     ResourceTypes,
     AccountPermissions,
     StorageErrorCode
 )
+from ._blob_utils import StorageStreamDownloader
 from .models import (
     BlobType,
     BlockState,
@@ -85,6 +87,8 @@
     'BlobPermissions',
     'ResourceTypes',
     'AccountPermissions',
+    'CopyStatusPoller',
+    'StorageStreamDownloader',
 ]
 
 
@@ -96,6 +100,7 @@ def upload_blob_to_url(
         encoding='UTF-8', # type: str
         credential=None,  # type: Any
         **kwargs):
+    # type: (...) -> dict[str, Any]
     """Upload data to a given URL
 
     The data will be uploaded as a block blob.
@@ -115,7 +120,7 @@ def upload_blob_to_url(
         shared access key, or an instance of a TokenCredentials class from azure.identity.
         If the URL already has a SAS token, specifying an explicit credential will take priority.
     :returns: Blob-updated property dict (Etag and last modified)
-    :rtype: dict[str, Any]
+    :rtype: dict(str, Any)
     """
     with BlobClient(blob_url, credential=credential) as client:
         return client.upload_blob(
@@ -128,6 +133,7 @@ def upload_blob_to_url(
 
 
 def _download_to_stream(client, handle, max_connections, **kwargs):
+    """Download data to specified open file-handle."""
     stream = client.download_blob(**kwargs)
     stream.download_to_stream(handle, max_connections=max_connections)
 
@@ -139,7 +145,8 @@ def download_blob_from_url(
         max_connections=1,  # type: int
         credential=None,  # type: Any
         **kwargs):
-    """Download the contents of a blob to a local file.
+    # type: (...) -> None
+    """Download the contents of a blob to a local file or stream.
 
     :param str blob_url:
         The full URI to the blob. This can also include a SAS token.

sdk/storage/azure-storage-blob/azure/storage/blob/_blob_utils.py

@@ -420,6 +420,11 @@ def deserialize_container_properties(response, obj, headers):
 
 
 class StorageStreamDownloader(object):  # pylint: disable=too-many-instance-attributes
+    """A streaming object to download a blob.
+
+    The stream downloader can iterated, or download to open file or stream
+    over multiple threads.
+    """
 
     def __init__(
             self, name, container, service, config, offset, length, validate_content,
@@ -599,15 +604,40 @@ def _initial_request(self):
 
 
     def content_as_bytes(self, max_connections=1):
+        """Download the contents of this blob.
+
+        This operation is blocking until all data is downloaded.
+
+        :param int max_connections:
+            The number of parallel connections with which to download.
+        :rtype: bytes
+        """
         stream = BytesIO()
         self.download_to_stream(stream, max_connections=max_connections)
         return stream.getvalue()
 
     def content_as_text(self, max_connections=1, encoding='UTF-8'):
+        """Download the contents of this blob, and decode as text.
+
+        This operation is blocking until all data is downloaded.
+
+        :param int max_connections:
+            The number of parallel connections with which to download.
+        :rtype: str
+        """
         content = self.content_as_bytes(max_connections=max_connections)
         return content.decode(encoding)
 
     def download_to_stream(self, stream, max_connections=1):
+        """Download the contents of this blob to a stream.
+
+        :param stream:
+            The stream to download to. This can be an open file-handle,
+            or any writable stream. The stream must be seekable if the download
+            uses more than one parallel connection.
+        :returns: The properties of the downloaded blob.
+        :rtype: ~azure.storage.blob.models.BlobProperties
+        """
         # the stream must be seekable if parallel download is required
         if max_connections > 1:
             error_message = "Target stream handle must be seekable."

sdk/storage/azure-storage-blob/azure/storage/blob/_shared/models.py

@@ -383,32 +383,31 @@ def __str__(self):
 
 
 class Services(object):
-    """
-    Specifies the services accessible with the account SAS.
+    """Specifies the services accessible with the account SAS.
 
     :cvar Services Services.BLOB: The blob service.
     :cvar Services Services.FILE: The file service
     :cvar Services Services.QUEUE: The queue service.
-    :cvar Services Services.TABLE: The table service.
     :param bool blob:
-        Access to any blob service, for example, the `.BlockBlobService`
+        Access for the `~azure.storage.blob.blob_service_client.BlobServiceClient`
     :param bool queue:
-        Access to the `.QueueService`
+        Access for the `~azure.storage.queue.queue_service_client.QueueServiceClient`
     :param bool file:
-        Access to the `.FileService`
-    :param bool table:
-        Access to the TableService
+        Access for the `~azure.storage.file.file_service_client.FileServiceClient`
     :param str _str:
         A string representing the services.
     """
 
-    def __init__(self, blob=False, queue=False, file=False, table=False, _str=None):
+    BLOB = None # type: Services
+    QUEUE = None # type: Services
+    FILE = None # type: Services
+
+    def __init__(self, blob=False, queue=False, file=False, _str=None):
         if not _str:
             _str = ''
         self.blob = blob or ('b' in _str)
         self.queue = queue or ('q' in _str)
         self.file = file or ('f' in _str)
-        self.table = table or ('t' in _str)
 
     def __or__(self, other):
         return Services(_str=str(self) + str(other))
@@ -419,11 +418,9 @@ def __add__(self, other):
     def __str__(self):
         return (('b' if self.blob else '') +
                 ('q' if self.queue else '') +
-                ('t' if self.table else '') +
                 ('f' if self.file else ''))
 
 
-Services.BLOB = Services(blob=True) # type: ignore
-Services.QUEUE = Services(queue=True) # type: ignore
-Services.TABLE = Services(table=True) # type: ignore
-Services.FILE = Services(file=True) # type: ignore
+Services.BLOB = Services(blob=True)
+Services.QUEUE = Services(queue=True)
+Services.FILE = Services(file=True)