0
# File System Operations
1

2
File system-level operations for managing directories, files, and access policies within a specific container. The FileSystemClient provides comprehensive management capabilities for hierarchical namespace operations.
3

4
## Capabilities
5

6
### FileSystemClient
7

8
Client to interact with a specific file system, providing operations for creating and managing directories and files within the file system scope.
9

10
```python { .api }
11
class FileSystemClient:
12
    """
13
    A client to interact with a specific Azure Data Lake Storage Gen2 file system.
14
    
15
    Attributes:
16
        url (str): The full endpoint URL to the file system, including SAS token if used
17
        primary_endpoint (str): The full primary endpoint URL
18
        primary_hostname (str): The hostname of the primary endpoint
19
        file_system_name (str): Name of the file system
20
    """
21
    
22
    def __init__(
23
        self,
24
        account_url: str,
25
        file_system_name: str,
26
        credential=None,
27
        **kwargs
28
    ):
29
        """
30
        Initialize the FileSystemClient.
31
        
32
        Args:
33
            account_url (str): The URL to the DataLake storage account
34
            file_system_name (str): Name of the file system
35
            credential: Authentication credential
36
            **kwargs: Additional client configuration options
37
        """
38
    
39
    @classmethod
40
    def from_connection_string(
41
        cls,
42
        conn_str: str,
43
        file_system_name: str,
44
        credential=None,
45
        **kwargs
46
    ) -> 'FileSystemClient':
47
        """
48
        Create FileSystemClient from connection string.
49
        
50
        Args:
51
            conn_str (str): Connection string for the storage account
52
            file_system_name (str): Name of the file system
53
            credential: Optional credential to override connection string auth
54
            **kwargs: Additional client configuration options
55
            
56
        Returns:
57
            FileSystemClient: The file system client instance
58
        """
59
    
60
    def close(self) -> None:
61
        """Close the client."""
62
        
63
    def __exit__(self, *args) -> None:
64
        """Context manager exit."""
65
```
66

67
**Usage Examples:**
68

69
```python
70
from azure.storage.filedatalake import FileSystemClient
71

72
# Create client directly
73
fs_client = FileSystemClient(
74
    account_url="https://mystorageaccount.dfs.core.windows.net",
75
    file_system_name="myfilesystem",
76
    credential="<account_key>"
77
)
78

79
# From connection string
80
fs_client = FileSystemClient.from_connection_string(
81
    "DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=<key>",
82
    file_system_name="myfilesystem"
83
)
84
```
85

86
### File System Management
87

88
Operations for creating, deleting, and managing the file system itself.
89

90
```python { .api }
91
def create_file_system(
92
    self,
93
    metadata: Dict[str, str] = None,
94
    public_access: PublicAccess = None,
95
    **kwargs
96
) -> Dict[str, Any]:
97
    """
98
    Create the file system.
99
    
100
    Args:
101
        metadata (dict, optional): Metadata key-value pairs
102
        public_access (PublicAccess, optional): Public access level
103
        **kwargs: Additional options
104
        
105
    Returns:
106
        dict: File system creation response headers
107
    """
108

109
def delete_file_system(self, **kwargs) -> None:
110
    """
111
    Delete the file system.
112
    
113
    Args:
114
        **kwargs: Additional options including lease conditions
115
    """
116

117
def exists(self, **kwargs) -> bool:
118
    """
119
    Check if the file system exists.
120
    
121
    Args:
122
        **kwargs: Additional options
123
        
124
    Returns:
125
        bool: True if file system exists, False otherwise
126
    """
127

128
def get_file_system_properties(self, **kwargs) -> FileSystemProperties:
129
    """
130
    Get file system properties.
131
    
132
    Args:
133
        **kwargs: Additional options including lease conditions
134
        
135
    Returns:
136
        FileSystemProperties: Properties of the file system
137
    """
138

139
def set_file_system_metadata(
140
    self,
141
    metadata: Dict[str, str],
142
    **kwargs
143
) -> Dict[str, Any]:
144
    """
145
    Set file system metadata.
146
    
147
    Args:
148
        metadata (dict): Metadata key-value pairs
149
        **kwargs: Additional options including conditions
150
        
151
    Returns:
152
        dict: Response headers
153
    """
154
```
155

156
### Access Policy Management
157

158
Operations for managing signed access policies and public access settings.
159

160
```python { .api }
161
def set_file_system_access_policy(
162
    self,
163
    signed_identifiers: Dict[str, AccessPolicy],
164
    public_access: PublicAccess = None,
165
    **kwargs
166
) -> Dict[str, Any]:
167
    """
168
    Set access policy for the file system.
169
    
170
    Args:
171
        signed_identifiers (dict): Signed access policies
172
        public_access (PublicAccess, optional): Public access level
173
        **kwargs: Additional options
174
        
175
    Returns:
176
        dict: Response headers
177
    """
178

179
def get_file_system_access_policy(self, **kwargs) -> Dict[str, Any]:
180
    """
181
    Get access policy for the file system.
182
    
183
    Args:
184
        **kwargs: Additional options
185
        
186
    Returns:
187
        dict: Access policy information including public access and signed identifiers
188
    """
189
```
190

191
### Directory Operations
192

193
Operations for creating, deleting, and managing directories within the file system.
194

195
```python { .api }
196
def create_directory(
197
    self,
198
    directory: Union[DirectoryProperties, str],
199
    metadata: Dict[str, str] = None,
200
    **kwargs
201
) -> DataLakeDirectoryClient:
202
    """
203
    Create a directory in the file system.
204
    
205
    Args:
206
        directory: Name of the directory or DirectoryProperties object
207
        metadata (dict, optional): Metadata key-value pairs
208
        **kwargs: Additional options including permissions and conditions
209
        
210
    Returns:
211
        DataLakeDirectoryClient: Client for the created directory
212
    """
213

214
def delete_directory(
215
    self,
216
    directory: Union[DirectoryProperties, str],
217
    **kwargs
218
) -> DataLakeDirectoryClient:
219
    """
220
    Delete a directory from the file system.
221
    
222
    Args:
223
        directory: Name of the directory or DirectoryProperties object
224
        **kwargs: Additional options including recursive delete and conditions
225
        
226
    Returns:
227
        DataLakeDirectoryClient: Client for the deleted directory
228
    """
229

230
def get_directory_client(
231
    self,
232
    directory: Union[DirectoryProperties, str]
233
) -> DataLakeDirectoryClient:
234
    """
235
    Get a DataLakeDirectoryClient for a specific directory.
236
    
237
    Args:
238
        directory: Name of the directory or DirectoryProperties object
239
        
240
    Returns:
241
        DataLakeDirectoryClient: Client for the specified directory
242
    """
243
```
244

245
### File Operations
246

247
Operations for creating, deleting, and managing files within the file system.
248

249
```python { .api }
250
def create_file(
251
    self,
252
    file: Union[FileProperties, str],
253
    **kwargs
254
) -> DataLakeFileClient:
255
    """
256
    Create a file in the file system.
257
    
258
    Args:
259
        file: Name/path of the file or FileProperties object
260
        **kwargs: Additional options including content settings, metadata, permissions
261
        
262
    Returns:
263
        DataLakeFileClient: Client for the created file
264
    """
265

266
def delete_file(
267
    self,
268
    file_path: Union[FileProperties, str],
269
    **kwargs
270
) -> DataLakeFileClient:
271
    """
272
    Delete a file from the file system.
273
    
274
    Args:
275
        file_path: Path to the file or FileProperties object
276
        **kwargs: Additional options including conditions
277
        
278
    Returns:
279
        DataLakeFileClient: Client for the deleted file
280
    """
281

282
def get_file_client(
283
    self,
284
    file_path: Union[FileProperties, str]
285
) -> DataLakeFileClient:
286
    """
287
    Get a DataLakeFileClient for a specific file.
288
    
289
    Args:
290
        file_path: Path to the file or FileProperties object
291
        
292
    Returns:
293
        DataLakeFileClient: Client for the specified file
294
    """
295
```
296

297
### Path Listing and Discovery
298

299
Operations for listing and discovering paths within the file system hierarchy.
300

301
```python { .api }
302
def get_paths(
303
    self,
304
    path: str = None,
305
    recursive: bool = True,
306
    max_results: int = None,
307
    **kwargs
308
) -> ItemPaged[PathProperties]:
309
    """
310
    List paths in the file system.
311
    
312
    Args:
313
        path (str, optional): Path prefix to filter results
314
        recursive (bool): Whether to list recursively (default: True)
315
        max_results (int, optional): Maximum number of results per page
316
        **kwargs: Additional options including upn (user principal names)
317
        
318
    Returns:
319
        ItemPaged[PathProperties]: Paged list of path properties
320
    """
321

322
def list_deleted_paths(self, **kwargs) -> ItemPaged[DeletedPathProperties]:
323
    """
324
    List deleted paths that can be restored.
325
    
326
    Args:
327
        **kwargs: Additional options including path_prefix and max_results
328
        
329
    Returns:
330
        ItemPaged[DeletedPathProperties]: Paged list of deleted path properties
331
    """
332
```
333

334
### Lease Management
335

336
Operations for acquiring and managing leases on the file system.
337

338
```python { .api }
339
def acquire_lease(
340
    self,
341
    lease_duration: int = -1,
342
    lease_id: str = None,
343
    **kwargs
344
) -> DataLakeLeaseClient:
345
    """
346
    Acquire a lease on the file system.
347
    
348
    Args:
349
        lease_duration (int): Duration of the lease in seconds (-1 for infinite)
350
        lease_id (str, optional): Proposed lease ID
351
        **kwargs: Additional options including conditions
352
        
353
    Returns:
354
        DataLakeLeaseClient: Lease client for managing the lease
355
    """
356
```
357

358
**Usage Examples:**
359

360
```python
361
from azure.storage.filedatalake import FileSystemClient, PublicAccess
362

363
# Create a file system client
364
fs_client = FileSystemClient(
365
    account_url="https://mystorageaccount.dfs.core.windows.net",
366
    file_system_name="myfilesystem",
367
    credential="<account_key>"
368
)
369

370
# Create the file system if it doesn't exist
371
if not fs_client.exists():
372
    fs_client.create_file_system(
373
        metadata={"purpose": "data-processing"},
374
        public_access=PublicAccess.FileSystem
375
    )
376

377
# List all paths in the file system
378
paths = fs_client.get_paths(recursive=True)
379
for path in paths:
380
    print(f"Path: {path.name}, Type: {'Directory' if path.is_directory else 'File'}")
381

382
# Create a directory structure
383
analytics_dir = fs_client.create_directory("analytics")
384
raw_data_dir = fs_client.create_directory("analytics/raw-data")
385

386
# Create a file
387
data_file = fs_client.create_file("analytics/processed/results.json")
388

389
# Acquire a lease for exclusive access
390
lease_client = fs_client.acquire_lease(lease_duration=30)
391
print(f"Acquired lease: {lease_client.id}")
392
```