Azure Storage File Client Library (v2.x)

2.1.0 · active · verified Fri Apr 10

The `azure-storage-file` library provides client-side support for interacting with Azure File Shares, enabling operations such as creating shares, directories, and files, as well as managing file content. This is the v2.x series of the client library, which adheres to an older API design. The current version is 2.1.0, and its release cadence has significantly slowed, with development efforts now focused on the newer v12+ `azure-storage-file-share` library.

Warnings

breaking This `azure-storage-file` library (v2.x) uses an older API style and is largely superseded by the `azure-storage-file-share` library (v12.x and above) from the `azure.storage.file` namespace. The newer library offers a more idiomatic Python API, improved error handling, and support for the latest Azure Storage features. New projects should use `azure-storage-file-share` (v12+).
Fix: For new projects or major updates, migrate to `azure-storage-file-share` (`pip install azure-storage-file-share`) and update your code to the new API style (e.g., `from azure.storage.file import ShareServiceClient`).
deprecated The `azure-storage-file` package (v2.x) is effectively deprecated in favor of the newer `azure-storage-file-share` package (v12.x+). While still functional, it will receive minimal updates and new features will not be backported. Consider migration to stay current with Azure SDK best practices.
Fix: Plan a migration path to `azure-storage-file-share` (v12.x+) for ongoing development and access to new features. Refer to Microsoft's migration guides for the Azure SDK for Python.
gotcha Authentication for this v2.x library primarily relies on shared account keys or connection strings. Direct support for Azure Active Directory (AAD) or Managed Identity (MSI) is not built into this version, requiring external mechanisms or use of the v12+ SDK for integrated AAD authentication.
Fix: Use account name and key/connection string for authentication. For AAD/MSI, consider upgrading to `azure-storage-file-share` (v12.x+) which has integrated support, or implement custom token fetching and signing for v2.x, which is complex.
gotcha When creating files using methods like `create_file_from_bytes`, the `length` of the file content must be explicitly and correctly provided. Mismatching the provided length with the actual content size can lead to partial uploads or corrupted files without immediate, clear error messages.
Fix: Always pass `len(content)` (for bytes) or `os.path.getsize(filepath)` (for local files) as the `length` parameter to ensure the file is created with the correct size on the server.

Install

pip install azure-storage-file Install `azure-storage-file`

Imports

FileService

from azure.storage.file import FileService

FilePermissions
```
from azure.storage.file import FilePermissions
```
Introduced in v2.1.0 for granular file/directory permissions.

Quickstart

This quickstart demonstrates how to initialize the `FileService` using an account name and key, then create an Azure File Share, a directory within it, and finally upload a file from a byte string. Remember to replace placeholder credentials with actual values, ideally from environment variables.

import os
from azure.storage.file import FileService

# Replace with your actual storage account name and key
# For production, use environment variables or a secure configuration management system.
ACCOUNT_NAME = os.environ.get("AZURE_STORAGE_ACCOUNT_NAME", "<YOUR_ACCOUNT_NAME>")
ACCOUNT_KEY = os.environ.get("AZURE_STORAGE_ACCOUNT_KEY", "<YOUR_ACCOUNT_KEY>")

if ACCOUNT_NAME == "<YOUR_ACCOUNT_NAME>" or ACCOUNT_KEY == "<YOUR_ACCOUNT_KEY>":
    print("Please set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY environment variables or replace placeholders.")
else:
    try:
        # Create a FileService object
        file_service = FileService(account_name=ACCOUNT_NAME, account_key=ACCOUNT_KEY)

        share_name = "mytestshare"
        directory_name = "mydirectory"
        file_name = "example.txt"
        file_content = b"Hello Azure File Share from v2.x!"

        # Create a share (if it doesn't exist)
        print(f"Creating share: {share_name}")
        file_service.create_share(share_name, fail_on_exist=False)

        # Create a directory (if it doesn't exist)
        print(f"Creating directory: {directory_name} in share {share_name}")
        file_service.create_directory(share_name, directory_name, fail_on_exist=False)

        # Upload a file from bytes
        print(f"Uploading file: {file_name} to {share_name}/{directory_name}")
        file_service.create_file_from_bytes(
            share_name,
            directory_name,
            file_name,
            file_content,
            len(file_content)
        )

        print(f"Successfully uploaded '{file_name}' to Azure File Share.")

        # Optional: List files in the directory
        print(f"Listing files in '{share_name}/{directory_name}':")
        files = file_service.list_files(share_name, directory_name)
        for file in files:
            print(f"- {file.name}")

        # Optional: Delete the file for cleanup
        # print(f"Deleting file: {file_name}")
        # file_service.delete_file(share_name, directory_name, file_name)

        # Optional: Delete the directory and share for cleanup
        # print(f"Deleting directory: {directory_name}")
        # file_service.delete_directory(share_name, directory_name)
        # print(f"Deleting share: {share_name}")
        # file_service.delete_share(share_name)

    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →