Samples for Files (#6730)

* samples for files

* update README

* update readme

* comments

Author: Rakshith Bhyravabhotla

sdk/storage/azure-storage-file/README.md

@@ -126,6 +126,87 @@ with open("./SampleSource.txt", "rb") as source_file:
     file_client.upload_file(source_file)
 ```
 
+### Download a file
+Download a file to the share
+
+```python
+from azure.storage.file import FileClient
+
+file_client = FileClient.from_connection_string("my_connection_string", share="share", file_path="myfile")
+
+with open("DEST_FILE", "wb") as data:
+    file_client.download_file(data)
+```
+
+### List contents of a directory.
+Lists all the directories and files under the directory.
+
+```python
+from azure.storage.file import ShareClient
+share = ShareClient.from_connection_string(self.connection_string, "subdirshare")
+parent_dir = share.get_directory_client(directory_path="parentdir")
+
+my_list = list(parent_dir.list_directories_and_files())
+print(my_list)
+```
+
+### Client creation with a connection string
+Create the FileServiceClient using the connection string to your Azure Storage account.
+
+```python
+from azure.storage.file.aio import FileServiceClient
+
+service = FileServiceClient.from_connection_string("my_connection_string")
+```
+
+### Create a file share asynchronously
+Create a file share to store your files.
+
+```python
+from azure.storage.file.aio import ShareClient
+
+share = ShareClient.from_connection_string("my_connection_string", share="myshare")
+await share.create_share()
+```
+
+### Upload a file asynchronously
+Upload a file to the share
+
+```python
+from azure.storage.file.aio import FileClient
+
+file_client = FileClient.from_connection_string("my_connection_string", share="share", file_path="myfile")
+
+with open("./SampleSource.txt", "rb") as source_file:
+    await file_client.upload_file(source_file)
+```
+
+### Download a file asynchronously
+Download a file to the share
+
+```python
+from azure.storage.file.aio import FileClient
+
+file_client = FileClient.from_connection_string("my_connection_string", share="share", file_path="myfile")
+
+with open("DEST_FILE", "wb") as data:
+    await file_client.download_file(data)
+```
+
+### List contents of a directory asynchronously
+Lists all the directories and files under the directory.
+
+```python
+from azure.storage.file import ShareClient
+share = ShareClient.from_connection_string(self.connection_string, "subdirshare")
+parent_dir = share.get_directory_client(directory_path="parentdir")
+
+my_files = []
+async for item in parent_dir.list_directories_and_files():
+    my_list.append(item)
+print(my_list)
+```
+
 ## Troubleshooting
 Storage File clients raise exceptions defined in [Azure Core](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/docs/exceptions.md).
 
@@ -139,38 +220,44 @@ Get started with our [File samples](https://github.com/Azure/azure-sdk-for-pytho
 Several Storage File Python SDK samples are available to you in the SDK's GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Storage File:
 
 * [`test_file_samples_hello_world.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_hello_world.py) - Examples found in this article:
+* [`test_file_samples_hello_world.py`]([async version]https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_hello_world_async.py) - Examples found in this article:
     * Client creation
     * Create a file share
     * Upload a file
 
 * [`test_file_samples_authentication.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_authentication.py) - Examples for authenticating and creating the client:
+* [`test_file_samples_authentication.py`]([async version]https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_authentication_async.py) - Examples for authenticating and creating the client:
     * From a connection string
     * From a shared access key
     * From a shared access signature token
 
 * [`test_file_samples_service.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_service.py) - Examples for interacting with the file service:
+* [`test_file_samples_service.py`]([async version]https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_service_async.py) - Examples for interacting with the file service:
     * Get and set service properties
     * Create, list, and delete shares
     * Get a share client
 
 * [`test_file_samples_share.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_share.py) - Examples for interacting with file shares:
+* [`test_file_samples_share.py`]([async version]https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_share_async.py) - Examples for interacting with file shares:
     * Create a share snapshot
     * Set share quota and metadata
     * List directories and files
     * Get the directory or file client to interact with a specific entity
 
 * [`test_file_samples_directory.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_directory.py) - Examples for interacting with directories:
+* [`test_file_samples_directory.py`]([async version]https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_directory_async.py) - Examples for interacting with directories:
     * Create a directory and add files
     * Create and delete subdirectories
     * Get the subdirectory client
 
 * [`test_file_samples_file.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_file.py) - Examples for interacting with files:
+* [`test_file_samples_file.py`]([async version]https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/test_file_samples_file_async.py) - Examples for interacting with files:
     * Create, upload, download, and delete files
     * Copy a file from a URL
 
 ### Additional documentation
 
-For more extensive documentation on the Azure Storage File, see the [Azure Storage File documentation](https://docs.microsoft.com/azure/storage/) on docs.microsoft.com.
+For more extensive documentation on the Azure Storage File, see the [Azure Storage File documentation](https://azure.github.io/azure-sdk-for-python/ref/azure.storage.file) on docs.microsoft.com.
 
 
 ## Contributing

sdk/storage/azure-storage-file/azure/storage/file/aio/directory_client_async.py

@@ -120,10 +120,10 @@ def get_subdirectory_client(self, directory_name, **kwargs):
         :param str directory_name:
             The name of the subdirectory.
         :returns: A Directory Client.
-        :rtype: ~azure.storage.file.directory_client.DirectoryClient
+        :rtype: ~azure.storage.file.aio.directory_client_async.DirectoryClient
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_directory.py
+            .. literalinclude:: ../tests/test_file_samples_directory_async.py
                 :start-after: [START get_subdirectory_client]
                 :end-before: [END get_subdirectory_client]
                 :language: python
@@ -154,7 +154,7 @@ async def create_directory( # type: ignore
         :rtype: dict(str, Any)
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_directory.py
+            .. literalinclude:: ../tests/test_file_samples_directory_async.py
                 :start-after: [START create_directory]
                 :end-before: [END create_directory]
                 :language: python
@@ -183,7 +183,7 @@ async def delete_directory(self, timeout=None, **kwargs):
         :rtype: None
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_directory.py
+            .. literalinclude:: ../tests/test_file_samples_directory_async.py
                 :start-after: [START delete_directory]
                 :end-before: [END delete_directory]
                 :language: python
@@ -209,7 +209,7 @@ def list_directories_and_files(self, name_starts_with=None, timeout=None, **kwar
         :rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.storage.file.models.DirectoryProperties]
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_directory.py
+            .. literalinclude:: ../tests/test_file_samples_directory_async.py
                 :start-after: [START lists_directory]
                 :end-before: [END lists_directory]
                 :language: python
@@ -366,10 +366,10 @@ async def create_subdirectory(
         :param int timeout:
             The timeout parameter is expressed in seconds.
         :returns: DirectoryClient
-        :rtype: ~azure.storage.file.directory_client.DirectoryClient
+        :rtype: ~azure.storage.file.aio.directory_client_async.DirectoryClient
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_directory.py
+            .. literalinclude:: ../tests/test_file_samples_directory_async.py
                 :start-after: [START create_subdirectory]
                 :end-before: [END create_subdirectory]
                 :language: python
@@ -396,7 +396,7 @@ async def delete_subdirectory(
         :rtype: None
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_directory.py
+            .. literalinclude:: ../tests/test_file_samples_directory_async.py
                 :start-after: [START delete_subdirectory]
                 :end-before: [END delete_subdirectory]
                 :language: python
@@ -448,10 +448,10 @@ async def upload_file(
         :param str encoding:
             Defaults to UTF-8.
         :returns: FileClient
-        :rtype: ~azure.storage.file.file_client.FileClient
+        :rtype: ~azure.storage.file.aio.file_client_async.FileClient
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_directory.py
+            .. literalinclude:: ../tests/test_file_samples_directory_async.py
                 :start-after: [START upload_file_to_directory]
                 :end-before: [END upload_file_to_directory]
                 :language: python
@@ -488,7 +488,7 @@ async def delete_file(
         :rtype: None
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_directory.py
+            .. literalinclude:: ../tests/test_file_samples_directory_async.py
                 :start-after: [START delete_file_in_directory]
                 :end-before: [END delete_file_in_directory]
                 :language: python

sdk/storage/azure-storage-file/azure/storage/file/aio/file_client_async.py

@@ -153,7 +153,7 @@ async def create_file(  # type: ignore
         :rtype: dict(str, Any)
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_file.py
+            .. literalinclude:: ../tests/test_file_samples_file_async.py
                 :start-after: [START create_file]
                 :end-before: [END create_file]
                 :language: python
@@ -230,7 +230,7 @@ async def upload_file(
         :rtype: dict(str, Any)
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_file.py
+            .. literalinclude:: ../tests/test_file_samples_file_async.py
                 :start-after: [START upload_file]
                 :end-before: [END upload_file]
                 :language: python
@@ -293,7 +293,7 @@ async def start_copy_from_url(
         :rtype: dict(str, Any)
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_file.py
+            .. literalinclude:: ../tests/test_file_samples_file_async.py
                 :start-after: [START copy_file_from_url]
                 :end-before: [END copy_file_from_url]
                 :language: python
@@ -368,7 +368,7 @@ async def download_file(
         :returns: A iterable data generator (stream)
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_file.py
+            .. literalinclude:: ../tests/test_file_samples_file_async.py
                 :start-after: [START download_file]
                 :end-before: [END download_file]
                 :language: python
@@ -407,7 +407,7 @@ async def delete_file(self, timeout=None, **kwargs):
         :rtype: None
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_file.py
+            .. literalinclude:: ../tests/test_file_samples_file_async.py
                 :start-after: [START delete_file]
                 :end-before: [END delete_file]
                 :language: python

sdk/storage/azure-storage-file/azure/storage/file/aio/file_service_client_async.py

@@ -66,7 +66,7 @@ class FileServiceClient(AsyncStorageAccountHostsMixin, FileServiceClientBase):
         shared access key.
 
     Example:
-        .. literalinclude:: ../tests/test_file_samples_authentication.py
+        .. literalinclude:: ../tests/test_file_samples_authentication_async.py
             :start-after: [START create_file_service_client]
             :end-before: [END create_file_service_client]
             :language: python
@@ -100,7 +100,7 @@ async def get_service_properties(self, timeout=None, **kwargs):
         :rtype: ~azure.storage.file._generated.models.StorageServiceProperties
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_service.py
+            .. literalinclude:: ../tests/test_file_samples_service_async.py
                 :start-after: [START get_service_properties]
                 :end-before: [END get_service_properties]
                 :language: python
@@ -143,7 +143,7 @@ async def set_service_properties(
         :rtype: None
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_service.py
+            .. literalinclude:: ../tests/test_file_samples_service_async.py
                 :start-after: [START set_service_properties]
                 :end-before: [END set_service_properties]
                 :language: python
@@ -185,7 +185,7 @@ def list_shares(
         :rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.storage.file.models.ShareProperties]
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_service.py
+            .. literalinclude:: ../tests/test_file_samples_service_async.py
                 :start-after: [START fsc_list_shares]
                 :end-before: [END fsc_list_shares]
                 :language: python
@@ -229,10 +229,10 @@ async def create_share(
             Quota in bytes.
         :param int timeout:
             The timeout parameter is expressed in seconds.
-        :rtype: ~azure.storage.file.share_client.ShareClient
+        :rtype: ~azure.storage.file.aio.share_client_async.ShareClient
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_service.py
+            .. literalinclude:: ../tests/test_file_samples_service_async.py
                 :start-after: [START fsc_create_shares]
                 :end-before: [END fsc_create_shares]
                 :language: python
@@ -265,7 +265,7 @@ async def delete_share(
         :rtype: None
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_service.py
+            .. literalinclude:: ../tests/test_file_samples_service_async.py
                 :start-after: [START fsc_delete_shares]
                 :end-before: [END fsc_delete_shares]
                 :language: python
@@ -288,10 +288,10 @@ def get_share_client(self, share, snapshot=None):
         :param str snapshot:
             An optional share snapshot on which to operate.
         :returns: A ShareClient.
-        :rtype: ~azure.storage.file.share_client.ShareClient
+        :rtype: ~azure.storage.file.aio.share_client_async.ShareClient
 
         Example:
-            .. literalinclude:: ../tests/test_file_samples_service.py
+            .. literalinclude:: ../tests/test_file_samples_service_async.py
                 :start-after: [START get_share_client]
                 :end-before: [END get_share_client]
                 :language: python