0
# Core Operations
1

2
Essential filesystem operations that form the foundation of the FS interface. These operations are available across all filesystem implementations and provide the basic functionality needed for file and directory manipulation.
3

4
## Capabilities
5

6
### File Operations
7

8
Open, create, read, and write files with support for text and binary modes.
9

10
```python { .api }
11
def open(self, path: str, mode: str = 'r', buffering: int = -1, encoding: str = None, errors: str = None, newline: str = None, **kwargs) -> IO:
12
    """
13
    Open a file for reading or writing.
14

15
    Parameters:
16
    - path: str, path to file
17
    - mode: str, file mode ('r', 'w', 'a', 'x', 'b', 't', '+')
18
    - buffering: int, buffer size (-1 for default)
19
    - encoding: str, text encoding (for text mode)
20
    - errors: str, error handling ('strict', 'ignore', 'replace')
21
    - newline: str, newline handling
22

23
    Returns:
24
    IO: File-like object
25

26
    Raises:
27
    - ResourceNotFound: If file doesn't exist (read mode)
28
    - FileExpected: If path is a directory
29
    - PermissionDenied: If insufficient permissions
30
    """
31

32
def create(self, path: str, wipe: bool = False) -> IO:
33
    """
34
    Create a new file and return file object.
35

36
    Parameters:
37
    - path: str, path to file
38
    - wipe: bool, overwrite if file exists
39

40
    Returns:
41
    IO: File object opened in binary write mode
42

43
    Raises:
44
    - FileExists: If file exists and wipe=False
45
    - DirectoryExpected: If parent directory doesn't exist
46
    """
47

48
def readtext(self, path: str, encoding: str = 'utf-8', errors: str = 'strict', newline: str = '') -> str:
49
    """
50
    Read text from a file.
51

52
    Parameters:
53
    - path: str, path to file
54
    - encoding: str, text encoding
55
    - errors: str, error handling
56
    - newline: str, newline handling
57

58
    Returns:
59
    str: File contents as text
60
    """
61

62
def writetext(self, path: str, contents: str, encoding: str = 'utf-8', errors: str = 'strict', newline: str = '') -> None:
63
    """
64
    Write text to a file.
65

66
    Parameters:
67
    - path: str, path to file
68
    - contents: str, text to write
69
    - encoding: str, text encoding
70
    - errors: str, error handling
71
    - newline: str, newline handling
72
    """
73

74
def readbytes(self, path: str) -> bytes:
75
    """
76
    Read bytes from a file.
77

78
    Parameters:
79
    - path: str, path to file
80

81
    Returns:
82
    bytes: File contents as bytes
83
    """
84

85
def writebytes(self, path: str, contents: bytes) -> None:
86
    """
87
    Write bytes to a file.
88

89
    Parameters:
90
    - path: str, path to file
91
    - contents: bytes, data to write
92
    """
93
```
94

95
### Directory Operations
96

97
Create, list, and remove directories with support for nested directory structures.
98

99
```python { .api }
100
def makedir(self, path: str, permissions: Permissions = None, recreate: bool = False) -> SubFS[FS]:
101
    """
102
    Create a directory.
103

104
    Parameters:
105
    - path: str, path to directory
106
    - permissions: Permissions, directory permissions
107
    - recreate: bool, don't raise error if directory exists
108

109
    Returns:
110
    SubFS[FS]: Filesystem representing the new directory
111

112
    Raises:
113
    - DirectoryExists: If directory exists and recreate=False
114
    - ResourceExists: If path exists as file
115
    """
116

117
def removedir(self, path: str) -> None:
118
    """
119
    Remove a directory.
120

121
    Parameters:
122
    - path: str, path to directory
123

124
    Raises:
125
    - DirectoryNotEmpty: If directory contains files
126
    - ResourceNotFound: If directory doesn't exist
127
    - DirectoryExpected: If path is a file
128
    """
129

130
def listdir(self, path: str = '.') -> List[str]:
131
    """
132
    List directory contents.
133

134
    Parameters:
135
    - path: str, path to directory
136

137
    Returns:
138
    List[str]: List of filenames and directory names
139

140
    Raises:
141
    - DirectoryExpected: If path is not a directory
142
    - ResourceNotFound: If directory doesn't exist
143
    """
144

145
def scandir(self, path: str = '.', namespaces: List[str] = None, page: Tuple[int, int] = None) -> Iterator[Info]:
146
    """
147
    Scan directory and return Info objects.
148

149
    Parameters:
150
    - path: str, path to directory
151
    - namespaces: List[str], info namespaces to retrieve
152
    - page: Tuple[int, int], pagination (start, end)
153

154
    Returns:
155
    Iterator[Info]: Info objects for directory contents
156
    """
157
```
158

159
### Path Queries
160

161
Query filesystem paths to determine existence, type, and properties.
162

163
```python { .api }
164
def exists(self, path: str) -> bool:
165
    """
166
    Check if path exists.
167

168
    Parameters:
169
    - path: str, path to check
170

171
    Returns:
172
    bool: True if path exists
173
    """
174

175
def isfile(self, path: str) -> bool:
176
    """
177
    Check if path is a file.
178

179
    Parameters:
180
    - path: str, path to check
181

182
    Returns:
183
    bool: True if path is a file
184
    """
185

186
def isdir(self, path: str) -> bool:
187
    """
188
    Check if path is a directory.
189

190
    Parameters:
191
    - path: str, path to check
192

193
    Returns:
194
    bool: True if path is a directory
195
    """
196

197
def gettype(self, path: str) -> ResourceType:
198
    """
199
    Get resource type.
200

201
    Parameters:
202
    - path: str, path to check
203

204
    Returns:
205
    ResourceType: Type of resource (file, directory, etc.)
206
    """
207

208
def getsize(self, path: str) -> int:
209
    """
210
    Get file size in bytes.
211

212
    Parameters:
213
    - path: str, path to file
214

215
    Returns:
216
    int: File size in bytes
217

218
    Raises:
219
    - ResourceNotFound: If file doesn't exist
220
    """
221
```
222

223
### File and Directory Removal
224

225
Remove files and directories from the filesystem.
226

227
```python { .api }
228
def remove(self, path: str) -> None:
229
    """
230
    Remove a file.
231

232
    Parameters:
233
    - path: str, path to file
234

235
    Raises:
236
    - ResourceNotFound: If file doesn't exist
237
    - FileExpected: If path is a directory
238
    """
239

240
def move(self, src_path: str, dst_path: str, overwrite: bool = False) -> None:
241
    """
242
    Move a file or directory.
243

244
    Parameters:
245
    - src_path: str, source path
246
    - dst_path: str, destination path
247
    - overwrite: bool, overwrite destination if exists
248

249
    Raises:
250
    - ResourceNotFound: If source doesn't exist
251
    - ResourceExists: If destination exists and overwrite=False
252
    """
253

254
def copy(self, src_path: str, dst_path: str, overwrite: bool = False) -> None:
255
    """
256
    Copy a file.
257

258
    Parameters:
259
    - src_path: str, source file path
260
    - dst_path: str, destination file path
261
    - overwrite: bool, overwrite destination if exists
262

263
    Raises:
264
    - ResourceNotFound: If source doesn't exist
265
    - ResourceExists: If destination exists and overwrite=False
266
    """
267
```
268

269
### Metadata Operations
270

271
Access and modify file and directory metadata including timestamps, permissions, and custom attributes.
272

273
```python { .api }
274
def getinfo(self, path: str, namespaces: List[str] = None) -> Info:
275
    """
276
    Get information about a resource.
277

278
    Parameters:
279
    - path: str, path to resource
280
    - namespaces: List[str], info namespaces to retrieve
281

282
    Returns:
283
    Info: Resource information object
284

285
    Raises:
286
    - ResourceNotFound: If resource doesn't exist
287
    """
288

289
def setinfo(self, path: str, info: RawInfo) -> None:
290
    """
291
    Set information on a resource.
292

293
    Parameters:
294
    - path: str, path to resource
295
    - info: RawInfo, information to set
296

297
    Raises:
298
    - ResourceNotFound: If resource doesn't exist
299
    """
300
```
301

302
### System Operations
303

304
Operations for filesystem lifecycle management and system-level functionality.
305

306
```python { .api }
307
def close(self) -> None:
308
    """Close the filesystem and release resources."""
309

310
def isclosed(self) -> bool:
311
    """
312
    Check if filesystem is closed.
313

314
    Returns:
315
    bool: True if filesystem is closed
316
    """
317

318
def getsyspath(self, path: str) -> str:
319
    """
320
    Get system path for a filesystem path.
321

322
    Parameters:
323
    - path: str, filesystem path
324

325
    Returns:
326
    str: System path
327

328
    Raises:
329
    - NoSysPath: If no system path available
330
    """
331

332
def geturl(self, path: str, purpose: str = 'download') -> str:
333
    """
334
    Get URL for a filesystem path.
335

336
    Parameters:
337
    - path: str, filesystem path
338
    - purpose: str, URL purpose ('download', 'upload', etc.)
339

340
    Returns:
341
    str: URL for the resource
342

343
    Raises:
344
    - NoURL: If no URL available
345
    """
346
```
347

348
## Types
349

350
```python { .api }
351
from typing import IO, List, Iterator, Tuple, Union
352

353
class SubFS:
354
    """Filesystem representing a subdirectory."""
355
    pass
356

357
class Info:
358
    """Resource information container."""
359
    pass
360

361
RawInfo = Dict[str, Dict[str, Any]]  # Raw info dictionary
362

363
class ResourceType(IntEnum):
364
    unknown = 0
365
    directory = 1
366
    file = 2
367
    character = 3
368
    block_special_file = 4
369
    fifo = 5
370
    socket = 6
371
    symlink = 7
372

373
class Permissions:
374
    """Unix-style permissions."""
375
    pass
376
```