Code samples for files

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

@@ -1,13 +1,13 @@
 # Azure Storage File client library for Python
-Azure File offers fully managed file shares in the cloud that are accessible via the industry standard [Server Message Block (SMB) protocol](https://docs.microsoft.com/en-us/windows/desktop/FileIO/microsoft-smb-protocol-and-cifs-protocol-overview). Azure file shares can be mounted concurrently by cloud or on-premises deployments of Windows, Linux, and macOS. Additionally, Azure file shares can be cached on Windows Servers with Azure File Sync for fast access near where the data is being used.
+Azure File offers fully managed file shares in the cloud that are accessible via the industry standard [Server Message Block (SMB) protocol](https://docs.microsoft.com/windows/desktop/FileIO/microsoft-smb-protocol-and-cifs-protocol-overview). Azure file shares can be mounted concurrently by cloud or on-premises deployments of Windows, Linux, and macOS. Additionally, Azure file shares can be cached on Windows Servers with Azure File Sync for fast access near where the data is being used.
 
 Azure file shares can be used to:
 
 * Replace or supplement on-premises file servers
 * "Lift and shift" applications
 * Simplify cloud development with shared application settings, diagnostic share, and Dev/Test/Debug tools
 
-[Source code](TODO) | [Package (PyPi)](TODO) | [API reference documentation](https://docs.microsoft.com/en-us/rest/api/storageservices/file-service-rest-api) | [Product documentation](https://docs.microsoft.com/en-us/azure/storage/) | [Samples](TODO)
+[Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/azure/storage/file) | [Package (PyPi)](https://pypi.org/project/azure-storage-file/) | [API reference documentation](https://docs.microsoft.com/rest/api/storageservices/file-service-rest-api) | [Product documentation](https://docs.microsoft.com/azure/storage/) | [Samples](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/samples)
 
 ## Getting started
 
@@ -18,11 +18,11 @@ Install the Azure Storage File client library for Python with [pip](https://pypi
 pip install azure-storage-file
 ```
 
-**Prerequisites**: You must have an [Azure subscription](https://azure.microsoft.com/en-us/free/), and a
-[Storage Account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview) to use this package.
+**Prerequisites**: You must have an [Azure subscription](https://azure.microsoft.com/free/), and a
+[Storage Account](https://docs.microsoft.com/azure/storage/common/storage-account-overview) to use this package.
 
-To create a Storage Account, you can use the [Azure Portal](https://docs.microsoft.com/en-us/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal),
-[Azure PowerShell](https://docs.microsoft.com/en-us/azure/storage/common/storage-quickstart-create-account?tabs=azure-powershell) or [Azure CLI](https://docs.microsoft.com/en-us/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli):
+To create a Storage Account, you can use the [Azure Portal](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal),
+[Azure PowerShell](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-powershell) or [Azure CLI](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli):
 
 ```bash
 az storage account create -n MyStorageAccountName -g MyResourceGroupName
@@ -84,7 +84,7 @@ The Storage File SDK provides four different clients to interact with the File S
     exist yet. It provides operations to create, upload, copy, and download files as well as more advanced
     operations.
 
-For details on path naming restrictions, see [Naming and Referencing Shares, Directories, Files, and Metadata](https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-shares--directories--files--and-metadata).
+For details on path naming restrictions, see [Naming and Referencing Shares, Directories, Files, and Metadata](https://docs.microsoft.com/rest/api/storageservices/naming-and-referencing-shares--directories--files--and-metadata).
 
 ## Examples
 
@@ -129,48 +129,48 @@ with open("./SampleSource.txt", "rb") as source_file:
 ## 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).
 
-All File service operations will throw a StorageErrorException on failure with helpful [error codes](https://docs.microsoft.com/en-us/rest/api/storageservices/file-service-error-codes).
+All File service operations will throw a StorageErrorException on failure with helpful [error codes](https://docs.microsoft.com/rest/api/storageservices/file-service-error-codes).
 
 ## Next steps
 ### More sample code
 
-Get started with our [File samples](TODO).
+Get started with our [File samples](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/samples).
 
 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_samples_hello_world.py`](TODO) - Examples found in this article:
+* [`test_samples_hello_world.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/samples/test_samples_hello_world.py) - Examples found in this article:
     * Client creation
     * Create a file share
     * Upload a file
 
-* [`test_samples_authentication.py`](TODO) - Examples for authenticating and creating the client:
+* [`test_samples_authentication.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/samples/test_samples_authentication.py) - Examples for authenticating and creating the client:
     * From a connection string
     * From a shared access key
     * From a shared access signature token
 
-* [`test_samples_file_service.py`](TODO) - Examples for interacting with the file service:
+* [`test_samples_file_service.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/samples/test_samples_file_service.py) - Examples for interacting with the file service:
     * Get and set service properties
     * Create, list, and delete shares
     * Get a share client
 
-* [`test_samples_share.py`](TODO) - Examples for interacting with file shares:
+* [`test_samples_share.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/samples/test_samples_share.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_samples_directory.py`](TODO) - Examples for interacting with directories:
+* [`test_samples_directory.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/samples/test_samples_directory.py) - Examples for interacting with directories:
     * Create a directory and add files
     * Create and delete subdirectories
     * Get the subdirectory client
 
-* [`test_samples_file.py`](TODO) - Examples for interacting with files:
+* [`test_samples_file.py`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-file/tests/samples/test_samples_file.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/en-us/azure/storage/) on docs.microsoft.com.
+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.
 
 
 ## Contributing

sdk/storage/azure-storage-file/azure/storage/file/directory_client.py

@@ -172,6 +172,14 @@ def get_subdirectory_client(self, directory_name, **kwargs):
             The name of the subdirectory.
         :returns: A Directory Client.
         :rtype: ~azure.core.file.directory_client.DirectoryClient
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_directory.py
+                :start-after: [START get_subdirectory_client]
+                :end-before: [END get_subdirectory_client]
+                :language: python
+                :dedent: 12
+                :caption: Gets the subdirectory client.
         """
         directory_path = self.directory_path.rstrip('/') + "/" + directory_name
         return DirectoryClient(
@@ -194,6 +202,14 @@ def create_directory(
             The timeout parameter is expressed in seconds.
         :returns: Directory-updated property dict (Etag and last modified).
         :rtype: dict(str, Any)
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_directory.py
+                :start-after: [START create_directory]
+                :end-before: [END create_directory]
+                :language: python
+                :dedent: 12
+                :caption: Creates a directory.
         """
         headers = kwargs.pop('headers', {})
         headers.update(add_metadata_headers(metadata))
@@ -214,6 +230,14 @@ def delete_directory(self, timeout=None, **kwargs):
         :param int timeout:
             The timeout parameter is expressed in seconds.
         :rtype: None
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_directory.py
+                :start-after: [START delete_directory]
+                :end-before: [END delete_directory]
+                :language: python
+                :dedent: 12
+                :caption: Deletes a directory.
         """
         try:
             self._client.directory.delete(timeout=timeout, **kwargs)
@@ -234,6 +258,14 @@ def list_directories_and_files(self, name_starts_with=None, marker=None, timeout
         :param int timeout:
             The timeout parameter is expressed in seconds.
         :returns: An auto-paging iterable of dict-like DirectoryProperties and FileProperties
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_directory.py
+                :start-after: [START lists_directory]
+                :end-before: [END lists_directory]
+                :language: python
+                :dedent: 12
+                :caption: List directories and files.
         """
         results_per_page = kwargs.pop('results_per_page', None)
         command = functools.partial(
@@ -365,6 +397,14 @@ def create_subdirectory(
             The timeout parameter is expressed in seconds.
         :returns: DirectoryClient
         :rtype: ~azure.storage.file.directory_client.DirectoryClient
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_directory.py
+                :start-after: [START create_subdirectory]
+                :end-before: [END create_subdirectory]
+                :language: python
+                :dedent: 12
+                :caption: Create a subdirectory.
         """
         subdir = self.get_subdirectory_client(directory_name)
         subdir.create_directory(metadata=metadata, timeout=timeout, **kwargs)
@@ -383,6 +423,14 @@ def delete_subdirectory(
         :param int timeout:
             The timeout parameter is expressed in seconds.
         :returns: None
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_directory.py
+                :start-after: [START delete_subdirectory]
+                :end-before: [END delete_subdirectory]
+                :language: python
+                :dedent: 12
+                :caption: Delete a subdirectory.
         """
         subdir = self.get_subdirectory_client(directory_name)
         subdir.delete_directory(timeout=timeout, **kwargs)
@@ -429,6 +477,14 @@ def upload_file(
             Defaults to UTF-8.
         :returns: FileClient
         :rtype: ~azure.storage.file.file_client.FileClient
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_directory.py
+                :start-after: [START upload_file_to_directory]
+                :end-before: [END upload_file_to_directory]
+                :language: python
+                :dedent: 12
+                :caption: Upload a file to a directory.
         """
         file_client = self.get_file_client(file_name)
         file_client.upload_file(
@@ -457,6 +513,14 @@ def delete_file(
         :param int timeout:
             The timeout parameter is expressed in seconds.
         :returns: None
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_directory.py
+                :start-after: [START delete_file_in_directory]
+                :end-before: [END delete_file_in_directory]
+                :language: python
+                :dedent: 12
+                :caption: Delete a file in a directory.
         """
         file_client = self.get_file_client(file_name)
         file_client.delete_file(timeout, **kwargs)

sdk/storage/azure-storage-file/azure/storage/file/file_client.py

@@ -146,6 +146,14 @@ def from_connection_string(
             The credential with which to authenticate. This is optional if the
             account URL already has a SAS token. The value can be a SAS token string or an account
             shared access key.
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_hello_world.py
+                :start-after: [START create_file_client]
+                :end-before: [END create_file_client]
+                :language: python
+                :dedent: 12
+                :caption: Creates the file client with connection string.
         """
         account_url, secondary, credential = parse_connection_str(conn_str, credential, 'file')
         if 'secondary_hostname' not in kwargs:
@@ -268,6 +276,14 @@ def create_file(
             The timeout parameter is expressed in seconds.
         :returns: File-updated property dict (Etag and last modified).
         :rtype: dict(str, Any)
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_file.py
+                :start-after: [START create_file]
+                :end-before: [END create_file]
+                :language: python
+                :dedent: 12
+                :caption: Create a file.
         """
         if self.require_encryption and not self.key_encryption_key:
             raise ValueError("Encryption required but no key was provided.")
@@ -334,6 +350,14 @@ def upload_file(
             Defaults to UTF-8.
         :returns: File-updated property dict (Etag and last modified).
         :rtype: dict(str, Any)
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_file.py
+                :start-after: [START upload_file]
+                :end-before: [END upload_file]
+                :language: python
+                :dedent: 12
+                :caption: Upload a file.
         """
         if self.require_encryption or (self.key_encryption_key is not None):
             raise ValueError("Encryption not supported.")
@@ -384,6 +408,14 @@ def copy_file_from_url(
             The timeout parameter is expressed in seconds.
         :returns: Polling object in order to wait on or abort the operation
         :rtype: ~azure.storage.file.polling.CopyStatusPoller
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_file.py
+                :start-after: [START copy_file_from_url]
+                :end-before: [END copy_file_from_url]
+                :language: python
+                :dedent: 12
+                :caption: Copy a file from a URL
         """
         headers = kwargs.pop('headers', {})
         headers.update(add_metadata_headers(metadata))
@@ -433,6 +465,14 @@ def download_file(
         :param int timeout:
             The timeout parameter is expressed in seconds.
         :returns: A iterable data generator (stream)
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_file.py
+                :start-after: [START download_file]
+                :end-before: [END download_file]
+                :language: python
+                :dedent: 12
+                :caption: Download a file.
         """
         if self.require_encryption or (self.key_encryption_key is not None):
             raise ValueError("Encryption not supported.")
@@ -459,6 +499,14 @@ def delete_file(self, timeout=None, **kwargs):
         :param int timeout:
             The timeout parameter is expressed in seconds.
         :rtype: None
+
+        Example:
+            .. literalinclude:: ../tests/samples/test_samples_file.py
+                :start-after: [START delete_file]
+                :end-before: [END delete_file]
+                :language: python
+                :dedent: 12
+                :caption: Delete a file.
         """
         try:
             self._client.file.delete(timeout=timeout, **kwargs)