Merge pull request #224591 from pauljewellmsft/pauljewell-dev-guide-python-blobs

Add blob articles for Python developer guide

Author: American-Dipper

articles/storage/blobs/TOC.yml

@@ -718,6 +718,24 @@ items:
               href: storage-blob-container-lease-python.md
             - name: Manage properties and metadata
               href: storage-blob-container-properties-metadata-python.md
+          - name: Blob actions
+            items:
+            - name: Upload blobs
+              href: storage-blob-upload-python.md
+            - name: Download blobs
+              href: storage-blob-download-python.md
+            - name: Copy blobs
+              href: storage-blob-copy-python.md
+            - name: List blobs
+              href: storage-blobs-list-python.md
+            - name: Delete and restore blobs
+              href: storage-blob-delete-python.md
+            - name: Find blobs using tags
+              href: storage-blob-tags-python.md
+            - name: Manage blob leases
+              href: storage-blob-lease-python.md
+            - name: Manage blob properties and metadata
+              href: storage-blob-properties-metadata-python.md
       - name: Test with a storage emulator
         items:
         - name: Use the Azurite open-source emulator

articles/storage/blobs/storage-blob-copy-python.md

@@ -0,0 +1,96 @@
+---
+title: Copy a blob with Python
+titleSuffix: Azure Storage
+description: Learn how to copy a blob in Azure Storage by using the Python client library.
+services: storage
+author: pauljewellmsft
+
+ms.author: pauljewell
+ms.date: 01/25/2023
+ms.service: storage
+ms.subservice: blobs
+ms.topic: how-to
+ms.devlang: python
+ms.custom: devx-track-python, devguide-python
+---
+
+# Copy a blob with Python
+
+This article shows how to copy a blob in a storage account using the [Azure Storage client library for Python](/python/api/overview/azure/storage). It also shows how to abort a pending copy operation.
+
+## About copying blobs
+
+A copy operation can perform any of the following actions:
+
+- Copy a source blob to a destination blob with a different name. The destination blob can be an existing blob of the same blob type (block, append, or page), or can be a new blob created by the copy operation.
+- Copy a source blob to a destination blob with the same name, effectively replacing the destination blob. Such a copy operation removes any uncommitted blocks and overwrites the destination blob's metadata.
+- Copy a source file in the Azure File service to a destination blob. The destination blob can be an existing block blob, or can be a new block blob created by the copy operation. Copying from files to page blobs or append blobs isn't supported.
+- Copy a snapshot over its base blob. By promoting a snapshot to the position of the base blob, you can restore an earlier version of a blob.
+- Copy a snapshot to a destination blob with a different name. The resulting destination blob is a writeable blob and not a snapshot.
+
+The source blob for a copy operation may be one of the following types:
+- Block blob
+- Append blob
+- Page blob
+- Blob snapshot
+- Blob version
+
+If the destination blob already exists, it must be of the same blob type as the source blob. An existing destination blob will be overwritten.
+
+The destination blob can't be modified while a copy operation is in progress. A destination blob can only have one outstanding copy operation. One way to enforce this requirement is to use a blob lease, as shown in the earlier code example. For more information on blob leases, see [Create and manage blob leases with Python](storage-blob-lease-python.md).
+
+The entire source blob or file is always copied. Copying a range of bytes or set of blocks isn't supported. When a blob is copied, its system properties are copied to the destination blob with the same values.
+
+## Copy a blob
+
+To copy a blob, use the following method:
+
+- [BlobClient.start_copy_from_url](/python/api/azure-storage-blob/azure.storage.blob.blobclient#azure-storage-blob-blobclient-start-copy-from-url)
+
+This method returns a dictionary containing *copy_status* and *copy_id*, which can be used to check the status of the copy operation. The *copy_status* property will be 'success' if the copy completed synchronously or 'pending' if the copy has been started asynchronously. For asynchronous copies, the status can be checked by polling the [get_blob_properties](/python/api/azure-storage-blob/azure.storage.blob.blobclient#azure-storage-blob-blobclient-get-blob-properties) method and checking *copy_status*. To force the copy operation to be synchronous, set *requires_sync* to `True`. To learn more about the underlying operation, see [REST API operations](#rest-api-operations).
+
+The following code example gets a `BlobClient` object representing an existing blob and copies it to a new blob in a different container within the same storage account. This example also gets a lease on the source blob before copying so that no other client can modify the blob until the copy is complete and the lease is broken.
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_copy_blob":::
+
+Sample output is similar to:
+
+```console
+Source blob lease state: leased
+Copy status: success
+Copy progress: 5/5
+Copy completion time: 2022-11-14T16:53:54Z
+Total bytes copied: 5
+Source blob lease state: broken
+```
+
+## Abort a copy operation
+
+If you have a pending copy operation and need to cancel it, you can abort the operation. Aborting a copy operation results in a destination blob of zero length and full metadata. To learn more about the underlying operation, see [REST API operations](#rest-api-operations).
+
+The metadata for the destination blob will have the new values copied from the source blob or set explicitly during the copy operation. To keep the original metadata from before the copy, make a snapshot of the destination blob before calling one of the copy methods. The final blob will be committed when the copy completes.
+
+To abort a copy operation, use the following method:
+
+- [BlobClient.abort_copy](/python/api/azure-storage-blob/azure.storage.blob.blobclient#azure-storage-blob-blobclient-abort-copy)
+
+The following example stops a pending copy and leaves a destination blob with zero length and full metadata:
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_abort_copy":::
+
+## Resources
+
+To learn more about copying blobs using the Azure Blob Storage client library for Python, see the following resources.
+
+### REST API operations
+
+The Azure SDK for Python contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar Python paradigms. The client library methods for copying blobs use the following REST API operations:
+
+- [Copy Blob From URL](/rest/api/storageservices/copy-blob-from-url) (REST API)
+- [Abort Copy Blob](/rest/api/storageservices/abort-copy-blob) (REST API)
+
+### Code samples
+
+- [View code samples from this article (GitHub)](https://github.com/Azure-Samples/AzureStorageSnippets/blob/master/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py)
+
+[!INCLUDE [storage-dev-guide-resources-python](../../../includes/storage-dev-guides/storage-dev-guide-resources-python.md)]

articles/storage/blobs/storage-blob-delete-python.md

@@ -0,0 +1,82 @@
+---
+title: Delete and restore a blob with Python
+titleSuffix: Azure Storage
+description: Learn how to delete and restore a blob in your Azure Storage account using the Python client library
+services: storage
+author: pauljewellmsft
+
+ms.author: pauljewell
+ms.date: 01/25/2023
+ms.service: storage
+ms.subservice: blobs
+ms.topic: how-to
+ms.devlang: python
+ms.custom: devx-track-python, devguide-python
+---
+
+# Delete and restore a blob with Python
+
+This article shows how to delete blobs using the [Azure Storage client library for Python](/python/api/overview/azure/storage). If you've enabled [soft delete for blobs](soft-delete-blob-overview.md), you can restore deleted blobs during the retention period.
+
+## Delete a blob
+
+To delete a blob, call the following method:
+
+- [BlobClient.delete_blob](/python/api/azure-storage-blob/azure.storage.blob.blobclient#azure-storage-blob-blobclient-delete-blob)
+
+The following example deletes a blob:
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_delete_blob":::
+
+If the blob has any associated snapshots, you must delete all of its snapshots to delete the blob. The following example deletes a blob and its snapshots:
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_delete_blob_snapshots":::
+
+To delete *only* the snapshots and not the blob itself, you can pass the parameter `delete_snapshots="only"`.
+
+## Restore a deleted blob
+
+Blob soft delete protects an individual blob and its versions, snapshots, and metadata from accidental deletes or overwrites by maintaining the deleted data in the system for a specified period of time. During the retention period, you can restore the blob to its state at deletion. After the retention period has expired, the blob is permanently deleted. For more information about blob soft delete, see [Soft delete for blobs](soft-delete-blob-overview.md).
+
+You can use the Azure Storage client libraries to restore a soft-deleted blob or snapshot. 
+
+#### Restore soft-deleted objects when versioning is disabled
+
+To restore deleted blobs when versioning is disabled, call the following method:
+
+- [BlobClient.undelete_blob](/python/api/azure-storage-blob/azure.storage.blob.blobclient#azure-storage-blob-blobclient-undelete-blob)
+
+This method restores the content and metadata of a soft-deleted blob and any associated soft-deleted snapshots. Calling this method for a blob that hasn't been deleted has no effect. 
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_restore_blob":::
+
+#### Restore soft-deleted objects when versioning is enabled
+
+To restore a soft-deleted blob when versioning is enabled, copy a previous version over the base blob. You can use the following method:
+
+- [start_copy_from_url](/python/api/azure-storage-blob/azure.storage.blob.blobclient#azure-storage-blob-blobclient-start-copy-from-url)
+
+The following code example gets the latest version of a deleted blob, and restores the latest version by copying it to the base blob:
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_restore_blob_version":::
+
+## Resources
+
+To learn more about how to delete blobs and restore deleted blobs using the Azure Blob Storage client library for Python, see the following resources.
+
+### REST API operations
+
+The Azure SDK for Python contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar Python paradigms. The client library methods for deleting blobs and restoring deleted blobs use the following REST API operations:
+
+- [Delete Blob](/rest/api/storageservices/delete-blob) (REST API)
+- [Undelete Blob](/rest/api/storageservices/undelete-blob) (REST API)
+
+### Code samples
+
+- [View code samples from this article (GitHub)](https://github.com/Azure-Samples/AzureStorageSnippets/blob/master/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py)
+
+[!INCLUDE [storage-dev-guide-resources-python](../../../includes/storage-dev-guides/storage-dev-guide-resources-python.md)]
+
+### See also
+
+- [Soft delete for blobs](soft-delete-blob-overview.md)

articles/storage/blobs/storage-blob-download-python.md

@@ -0,0 +1,63 @@
+---
+title: Download a blob with Python
+titleSuffix: Azure Storage
+description: Learn how to download a blob in Azure Storage by using the Python client library.
+services: storage
+author: pauljewellmsft
+
+ms.author: pauljewell
+ms.date: 01/24/2023
+ms.service: storage
+ms.subservice: blobs
+ms.topic: how-to
+ms.devlang: python
+ms.custom: devx-track-python, devguide-python
+---
+
+# Download a blob with Python
+
+This article shows how to download a blob using the [Azure Storage client library for Python](/python/api/overview/azure/storage). You can download a blob by using the following method:
+
+- [BlobClient.download_blob](/python/api/azure-storage-blob/azure.storage.blob.blobclient#azure-storage-blob-blobclient-download-blob)
+
+The `download_blob` method returns a [StorageStreamDownloader](/python/api/azure-storage-blob/azure.storage.blob.storagestreamdownloader) object.
+ 
+## Download to a file path
+
+The following example downloads a blob to a file path:
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_download_blob_file":::
+
+## Download to a stream
+
+The following example downloads a blob to a stream. In this example, [StorageStreamDownloader.read_into](/python/api/azure-storage-blob/azure.storage.blob.storagestreamdownloader#azure-storage-blob-storagestreamdownloader-readinto) downloads the blob contents to a stream and returns the number of bytes read:
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_download_blob_stream":::
+
+## Download a blob in chunks
+
+The following example downloads a blob and iterates over chunks in the download stream. In this example, [StorageStreamDownloader.chunks](/python/api/azure-storage-blob/azure.storage.blob.storagestreamdownloader#azure-storage-blob-storagestreamdownloader-chunks) returns an iterator, which allows you to read the blob content in chunks:
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_download_blob_chunks":::
+
+## Download to a string
+
+The following example downloads blob contents as text. In this example, the `encoding` parameter is necessary for `readall()` to return a string, otherwise it returns bytes:
+
+:::code language="python" source="~/azure-storage-snippets/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py" id="Snippet_download_blob_text":::
+
+## Resources
+
+To learn more about how to download blobs using the Azure Blob Storage client library for Python, see the following resources.
+
+### REST API operations
+
+The Azure SDK for Python contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar Python paradigms. The client library methods for downloading blobs use the following REST API operation:
+
+- [Get Blob](/rest/api/storageservices/get-blob) (REST API)
+
+### Code samples
+
+- [View code samples from this article (GitHub)](https://github.com/Azure-Samples/AzureStorageSnippets/blob/master/blobs/howto/python/blob-devguide-py/blob-devguide-blobs.py)
+
+[!INCLUDE [storage-dev-guide-resources-python](../../../includes/storage-dev-guides/storage-dev-guide-resources-python.md)]