Develop Python applications that use Azure Files

Article
05/13/2024

Learn the basics of using Python to develop apps or services that use Azure Files to store file data. Create a console app and learn how to perform basic actions with Python and Azure Files:

Create Azure file shares
Create directories
Enumerate files and directories in an Azure file share
Upload, download, and delete a file
Create file share backups by using snapshots

Note

Because Azure Files may be accessed over SMB, it's possible to write simple applications that access the Azure file share using the standard Python I/O classes and functions. This article describes how to write apps that use the Azure Storage SDK for Python, which uses the Azure Files REST API to talk to Azure Files.

Applies to

File share type	SMB	NFS
Standard file shares (GPv2), LRS/ZRS
Standard file shares (GPv2), GRS/GZRS
Premium file shares (FileStorage), LRS/ZRS

Download and Install Azure Storage SDK for Python

Note

If you're upgrading from the Azure Storage SDK for Python version 0.36 or earlier, uninstall the older SDK using pip uninstall azure-storage before installing the latest package.

The Azure Files client library for Python requires Python 3.8+.

Install via PyPI

To install via the Python Package Index (PyPI), type:

pip install azure-storage-file-share

Set up your application to use Azure Files

Add the following code near the top of a Python source file to use the code snippets in this article.

from azure.core.exceptions import (
    ResourceExistsError,
    ResourceNotFoundError
)

from azure.storage.fileshare import (
    ShareServiceClient,
    ShareClient,
    ShareDirectoryClient,
    ShareFileClient
)

Set up a connection to Azure Files

ShareServiceClient lets you work with shares, directories, and files. This code creates a ShareServiceClient object using the storage account connection string:

# Create a ShareServiceClient from a connection string
service_client = ShareServiceClient.from_connection_string(connection_string)

The following code example uses a ShareClient object to create the share if it doesn't exist.

def create_file_share(self, connection_string, share_name):
    try:
        # Create a ShareClient from a connection string
        share_client = ShareClient.from_connection_string(
            connection_string, share_name)

        print("Creating share:", share_name)
        share_client.create_share()

    except ResourceExistsError as ex:
        print("ResourceExistsError:", ex.message)

Create a directory

You can organize storage by putting files inside subdirectories instead of having all of them in the root directory.

The following method creates a directory in the root of the specified file share by using a ShareDirectoryClient object.

def create_directory(self, connection_string, share_name, dir_name):
    try:
        # Create a ShareDirectoryClient from a connection string
        dir_client = ShareDirectoryClient.from_connection_string(
            connection_string, share_name, dir_name)

        print("Creating directory:", share_name + "/" + dir_name)
        dir_client.create_directory()

    except ResourceExistsError as ex:
        print("ResourceExistsError:", ex.message)

Upload a file

In this section, you learn how to upload a file from local storage into Azure Files.

The following method uploads the contents of the specified file into the specified directory in the specified Azure file share.

def upload_local_file(self, connection_string, local_file_path, share_name, dest_file_path):
    try:
        source_file = open(local_file_path, "rb")
        data = source_file.read()

        # Create a ShareFileClient from a connection string
        file_client = ShareFileClient.from_connection_string(
            connection_string, share_name, dest_file_path)

        print("Uploading to:", share_name + "/" + dest_file_path)
        file_client.upload_file(data)

    except ResourceExistsError as ex:
        print("ResourceExistsError:", ex.message)

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

To list the files and directories in a subdirectory, use the list_directories_and_files method. This method returns an auto-paging iterable. The following code outputs the name of each file and subdirectory in the specified directory to the console.

def list_files_and_dirs(self, connection_string, share_name, dir_name):
    try:
        # Create a ShareClient from a connection string
        share_client = ShareClient.from_connection_string(
            connection_string, share_name)

        for item in list(share_client.list_directories_and_files(dir_name)):
            if item["is_directory"]:
                print("Directory:", item["name"])
            else:
                print("File:", dir_name + "/" + item["name"])

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

Download a file

To download data from a file, use download_file.

The following example demonstrates using download_file to get the contents of the specified file and store it locally with DOWNLOADED- prepended to the filename.

def download_azure_file(self, connection_string, share_name, dir_name, file_name):
    try:
        # Build the remote path
        source_file_path = dir_name + "/" + file_name

        # Add a prefix to the filename to 
        # distinguish it from the uploaded file
        dest_file_name = "DOWNLOADED-" + file_name

        # Create a ShareFileClient from a connection string
        file_client = ShareFileClient.from_connection_string(
            connection_string, share_name, source_file_path)

        print("Downloading to:", dest_file_name)

        # Open a file for writing bytes on the local system
        with open(dest_file_name, "wb") as data:
            # Download the file from Azure into a stream
            stream = file_client.download_file()
            # Write the stream to the local file
            data.write(stream.readall())

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

You can create a point in time copy of your entire file share.

def create_snapshot(self, connection_string, share_name):
    try:
        # Create a ShareClient from a connection string
        share_client = ShareClient.from_connection_string(
            connection_string, share_name)

        # Create a snapshot
        snapshot = share_client.create_snapshot()
        print("Created snapshot:", snapshot["snapshot"])

        # Return the snapshot time so 
        # it can be accessed later
        return snapshot["snapshot"]

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

List shares and snapshots

You can list all the snapshots for a particular share.

def list_shares_snapshots(self, connection_string):
    try:
        # Create a ShareServiceClient from a connection string
        service_client = ShareServiceClient.from_connection_string(connection_string)

        # List the shares in the file service
        shares = list(service_client.list_shares(include_snapshots=True))

        for share in shares:
            if (share["snapshot"]):
                print("Share:", share["name"], "Snapshot:", share["snapshot"])
            else:
                print("Share:", share["name"])

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

You can browse each share snapshot to retrieve files and directories from that point in time.

def browse_snapshot_dir(self, connection_string, share_name, snapshot_time, dir_name):
    try:
        # Create a ShareClient from a connection string
        snapshot = ShareClient.from_connection_string(
            conn_str=connection_string, share_name=share_name, snapshot=snapshot_time)

        print("Snapshot:", snapshot_time)

        for item in list(snapshot.list_directories_and_files(dir_name)):
            if item["is_directory"]:
                print("Directory:", item["name"])
            else:
                print("File:", dir_name + "/" + item["name"])

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

You can download a file from a share snapshot, which enables you to restore a previous version of a file.

def download_snapshot_file(self, connection_string, share_name, snapshot_time, dir_name, file_name):
    try:
        # Build the remote path
        source_file_path = dir_name + "/" + file_name

        # Add a prefix to the local filename to 
        # indicate it's a file from a snapshot
        dest_file_name = "SNAPSHOT-" + file_name

        # Create a ShareFileClient from a connection string
        snapshot_file_client = ShareFileClient.from_connection_string(
            conn_str=connection_string, share_name=share_name, 
            file_path=source_file_path, snapshot=snapshot_time)

        print("Downloading to:", dest_file_name)

        # Open a file for writing bytes on the local system
        with open(dest_file_name, "wb") as data:
            # Download the file from Azure into a stream
            stream = snapshot_file_client.download_file()
            # Write the stream to the local file
            data.write(stream.readall())

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

You can delete a single share snapshot.

def delete_snapshot(self, connection_string, share_name, snapshot_time):
    try:
        # Create a ShareClient for a snapshot
        snapshot_client = ShareClient.from_connection_string(conn_str=connection_string, share_name=share_name, snapshot=snapshot_time)

        print("Deleting snapshot:", snapshot_time)

        # Delete the snapshot
        snapshot_client.delete_share()

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

Delete a file

To delete a file, call delete_file.

def delete_azure_file(self, connection_string, share_name, file_path):
    try:
        # Create a ShareFileClient from a connection string
        file_client = ShareFileClient.from_connection_string(
            connection_string, share_name, file_path)

        print("Deleting file:", share_name + "/" + file_path)

        # Delete the file
        file_client.delete_file()

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

To delete a share that contains snapshots, call delete_share with delete_snapshots=True.

def delete_share(self, connection_string, share_name):
    try:
        # Create a ShareClient from a connection string
        share_client = ShareClient.from_connection_string(
            connection_string, share_name)

        print("Deleting share:", share_name)

        # Delete the share and snapshots
        share_client.delete_share(delete_snapshots=True)

    except ResourceNotFoundError as ex:
        print("ResourceNotFoundError:", ex.message)

Next steps

Now that you've learned how to manipulate Azure Files with Python, follow these links to learn more.

For related code samples using deprecated Python version 2 SDKs, see Code samples using Python version 2.

Share via

Develop Python applications that use Azure Files

Applies to

Download and Install Azure Storage SDK for Python

Install via PyPI

Set up your application to use Azure Files

Set up a connection to Azure Files

Create a directory

Upload a file

Download a file

List shares and snapshots

Delete a file

Next steps

Feedback

Additional resources

Share via

Develop Python applications that use Azure Files

Applies to

Download and Install Azure Storage SDK for Python

Install via PyPI

Set up your application to use Azure Files

Set up a connection to Azure Files

Create an Azure file share

Create a directory

Upload a file

Enumerate files and directories in an Azure file share

Download a file

Create a share snapshot

List shares and snapshots

Browse share snapshot

Get file from share snapshot

Delete a single share snapshot

Delete a file

Delete share when share snapshots exist

Next steps

Feedback

Additional resources