Azure Storage File Share Py

1---
2name: azure-storage-file-share-py
3description: |
4  Azure Storage File Share SDK for Python. Use for SMB file shares, directories, and file operations in the cloud.
5  Triggers: "azure-storage-file-share", "ShareServiceClient", "ShareClient", "file share", "SMB".
6---
7 
8# Azure Storage File Share SDK for Python
9 
10Manage SMB file shares for cloud-native and lift-and-shift scenarios.
11 
12## Installation
13 
14```bash
15pip install azure-storage-file-share
16```
17 
18## Environment Variables
19 
20```bash
21AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...
22# Or
23AZURE_STORAGE_ACCOUNT_URL=https://<account>.file.core.windows.net
24```
25 
26## Authentication
27 
28### Connection String
29 
30```python
31from azure.storage.fileshare import ShareServiceClient
32 
33service = ShareServiceClient.from_connection_string(
34    os.environ["AZURE_STORAGE_CONNECTION_STRING"]
35)
36```
37 
38### Entra ID
39 
40```python
41from azure.storage.fileshare import ShareServiceClient
42from azure.identity import DefaultAzureCredential
43 
44service = ShareServiceClient(
45    account_url=os.environ["AZURE_STORAGE_ACCOUNT_URL"],
46    credential=DefaultAzureCredential()
47)
48```
49 
50## Share Operations
51 
52### Create Share
53 
54```python
55share = service.create_share("my-share")
56```
57 
58### List Shares
59 
60```python
61for share in service.list_shares():
62    print(f"{share.name}: {share.quota} GB")
63```
64 
65### Get Share Client
66 
67```python
68share_client = service.get_share_client("my-share")
69```
70 
71### Delete Share
72 
73```python
74service.delete_share("my-share")
75```
76 
77## Directory Operations
78 
79### Create Directory
80 
81```python
82share_client = service.get_share_client("my-share")
83share_client.create_directory("my-directory")
84 
85# Nested directory
86share_client.create_directory("my-directory/sub-directory")
87```
88 
89### List Directories and Files
90 
91```python
92directory_client = share_client.get_directory_client("my-directory")
93 
94for item in directory_client.list_directories_and_files():
95    if item["is_directory"]:
96        print(f"[DIR] {item['name']}")
97    else:
98        print(f"[FILE] {item['name']} ({item['size']} bytes)")
99```
100 
101### Delete Directory
102 
103```python
104share_client.delete_directory("my-directory")
105```
106 
107## File Operations
108 
109### Upload File
110 
111```python
112file_client = share_client.get_file_client("my-directory/file.txt")
113 
114# From string
115file_client.upload_file("Hello, World!")
116 
117# From file
118with open("local-file.txt", "rb") as f:
119    file_client.upload_file(f)
120 
121# From bytes
122file_client.upload_file(b"Binary content")
123```
124 
125### Download File
126 
127```python
128file_client = share_client.get_file_client("my-directory/file.txt")
129 
130# To bytes
131data = file_client.download_file().readall()
132 
133# To file
134with open("downloaded.txt", "wb") as f:
135    data = file_client.download_file()
136    data.readinto(f)
137 
138# Stream chunks
139download = file_client.download_file()
140for chunk in download.chunks():
141    process(chunk)
142```
143 
144### Get File Properties
145 
146```python
147properties = file_client.get_file_properties()
148print(f"Size: {properties.size}")
149print(f"Content type: {properties.content_settings.content_type}")
150print(f"Last modified: {properties.last_modified}")
151```
152 
153### Delete File
154 
155```python
156file_client.delete_file()
157```
158 
159### Copy File
160 
161```python
162source_url = "https://account.file.core.windows.net/share/source.txt"
163dest_client = share_client.get_file_client("destination.txt")
164dest_client.start_copy_from_url(source_url)
165```
166 
167## Range Operations
168 
169### Upload Range
170 
171```python
172# Upload to specific range
173file_client.upload_range(data=b"content", offset=0, length=7)
174```
175 
176### Download Range
177 
178```python
179# Download specific range
180download = file_client.download_file(offset=0, length=100)
181data = download.readall()
182```
183 
184## Snapshot Operations
185 
186### Create Snapshot
187 
188```python
189snapshot = share_client.create_snapshot()
190print(f"Snapshot: {snapshot['snapshot']}")
191```
192 
193### Access Snapshot
194 
195```python
196snapshot_client = service.get_share_client(
197    "my-share",
198    snapshot=snapshot["snapshot"]
199)
200```
201 
202## Async Client
203 
204```python
205from azure.storage.fileshare.aio import ShareServiceClient
206from azure.identity.aio import DefaultAzureCredential
207 
208async def upload_file():
209    credential = DefaultAzureCredential()
210    service = ShareServiceClient(account_url, credential=credential)
211    
212    share = service.get_share_client("my-share")
213    file_client = share.get_file_client("test.txt")
214    
215    await file_client.upload_file("Hello!")
216    
217    await service.close()
218    await credential.close()
219```
220 
221## Client Types
222 
223| Client | Purpose |
224|--------|---------|
225| `ShareServiceClient` | Account-level operations |
226| `ShareClient` | Share operations |
227| `ShareDirectoryClient` | Directory operations |
228| `ShareFileClient` | File operations |
229 
230## Best Practices
231 
2321. **Use connection string** for simplest setup
2332. **Use Entra ID** for production with RBAC
2343. **Stream large files** using chunks() to avoid memory issues
2354. **Create snapshots** before major changes
2365. **Set quotas** to prevent unexpected storage costs
2376. **Use ranges** for partial file updates
2387. **Close async clients** explicitly
239