0
# Filesystem Types
1

2
Concrete filesystem implementations for different storage backends including local directories, memory filesystems, archives, and network filesystems. Each implementation provides the same FS interface while handling the specifics of its storage type.
3

4
## Capabilities
5

6
### Operating System Filesystem
7

8
Access to the local operating system filesystem with full read/write capabilities.
9

10
```python { .api }
11
class OSFS(FS):
12
    """Operating system filesystem."""
13
    
14
    def __init__(self, root_path: str, create: bool = False, create_mode: int = 0o777) -> None:
15
        """
16
        Create OSFS for a directory path.
17

18
        Parameters:
19
        - root_path: str, path to root directory
20
        - create: bool, create directory if it doesn't exist
21
        - create_mode: int, permissions for created directory
22
        """
23
```
24

25
### Memory Filesystem
26

27
Fast in-memory filesystem for temporary data and testing.
28

29
```python { .api }
30
class MemoryFS(FS):
31
    """In-memory filesystem."""
32
    
33
    def __init__(self) -> None:
34
        """Create empty memory filesystem."""
35
```
36

37
### ZIP Archive Filesystem
38

39
Read and write ZIP archive files as filesystems.
40

41
```python { .api }
42
class ZipFS(FS):
43
    """ZIP archive filesystem."""
44
    
45
    def __init__(self, file: Union[str, IO], write: bool = False, compression: str = 'deflate', 
46
                 allowZip64: bool = True, encoding: str = 'utf-8') -> None:
47
        """
48
        Create ZipFS from ZIP file.
49

50
        Parameters:
51
        - file: str or file-like object, ZIP file path or object
52
        - write: bool, open for writing
53
        - compression: str, compression method ('deflate', 'stored', 'bzip2', 'lzma')
54
        - allowZip64: bool, enable ZIP64 extensions
55
        - encoding: str, encoding for filenames
56
        """
57
```
58

59
### TAR Archive Filesystem
60

61
Read and write TAR archive files as filesystems.
62

63
```python { .api }
64
class TarFS(FS):
65
    """TAR archive filesystem."""
66
    
67
    def __init__(self, file: Union[str, IO], write: bool = False, compression: str = None,
68
                 encoding: str = 'utf-8') -> None:
69
        """
70
        Create TarFS from TAR file.
71

72
        Parameters:
73
        - file: str or file-like object, TAR file path or object
74
        - write: bool, open for writing
75
        - compression: str, compression method ('gz', 'bz2', 'xz', None)
76
        - encoding: str, encoding for filenames
77
        """
78
```
79

80
### FTP Filesystem
81

82
Access FTP servers as filesystems with network connectivity.
83

84
```python { .api }
85
class FTPFS(FS):
86
    """FTP filesystem."""
87
    
88
    def __init__(self, host: str, user: str = 'anonymous', passwd: str = '', 
89
                 acct: str = '', timeout: int = 10, port: int = 21, 
90
                 proxy: str = None, tls: bool = False) -> None:
91
        """
92
        Create FTP filesystem.
93

94
        Parameters:
95
        - host: str, FTP server hostname
96
        - user: str, username
97
        - passwd: str, password
98
        - acct: str, account
99
        - timeout: int, connection timeout in seconds
100
        - port: int, FTP port
101
        - proxy: str, proxy server
102
        - tls: bool, use FTP over TLS
103
        """
104
```
105

106
### Temporary Filesystem
107

108
Temporary directory with automatic cleanup when closed.
109

110
```python { .api }
111
class TempFS(FS):
112
    """Temporary filesystem."""
113
    
114
    def __init__(self, identifier: str = 'fs', auto_clean: bool = True, 
115
                 temp_dir: str = None) -> None:
116
        """
117
        Create temporary filesystem.
118

119
        Parameters:
120
        - identifier: str, identifier for temp directory name
121
        - auto_clean: bool, automatically clean up on close
122
        - temp_dir: str, parent directory for temp filesystem
123
        """
124
```
125

126
### Application Filesystem
127

128
Filesystem for application data directories following platform conventions.
129

130
```python { .api }
131
class AppFS(FS):
132
    """Application data filesystem."""
133
    
134
    def __init__(self, appname: str, author: str = None, version: str = None, 
135
                 roaming: bool = False, create: bool = True) -> None:
136
        """
137
        Create application filesystem.
138

139
        Parameters:
140
        - appname: str, application name
141
        - author: str, application author
142
        - version: str, application version
143
        - roaming: bool, use roaming profile (Windows)
144
        - create: bool, create directory if it doesn't exist
145
        """
146
```
147

148
### Sub Filesystem
149

150
View of a subdirectory within another filesystem.
151

152
```python { .api }
153
class SubFS(FS):
154
    """Subdirectory filesystem view."""
155
    
156
    def __init__(self, parent_fs: FS, path: str) -> None:
157
        """
158
        Create SubFS for a directory.
159

160
        Parameters:
161
        - parent_fs: FS, parent filesystem
162
        - path: str, path to subdirectory
163
        """
164
```
165

166
### Mount Filesystem
167

168
Mount multiple filesystems at different paths in a single namespace.
169

170
```python { .api }
171
class MountFS(FS):
172
    """Mount multiple filesystems."""
173
    
174
    def __init__(self, auto_close: bool = True) -> None:
175
        """
176
        Create mount filesystem.
177

178
        Parameters:
179
        - auto_close: bool, automatically close mounted filesystems
180
        """
181
    
182
    def mount(self, path: str, fs: FS) -> None:
183
        """
184
        Mount filesystem at path.
185

186
        Parameters:
187
        - path: str, mount point path
188
        - fs: FS, filesystem to mount
189
        """
190
    
191
    def unmount(self, path: str) -> FS:
192
        """
193
        Unmount filesystem at path.
194

195
        Parameters:
196
        - path: str, mount point path
197

198
        Returns:
199
        FS: Unmounted filesystem
200
        """
201
```
202

203
### Multi Filesystem
204

205
Layer multiple filesystems with fallback behavior for read operations.
206

207
```python { .api }
208
class MultiFS(FS):
209
    """Multiple filesystem with fallback."""
210
    
211
    def __init__(self, auto_close: bool = True) -> None:
212
        """
213
        Create multi filesystem.
214

215
        Parameters:
216
        - auto_close: bool, automatically close added filesystems
217
        """
218
    
219
    def add_fs(self, name: str, fs: FS, write: bool = False, priority: int = 0) -> None:
220
        """
221
        Add filesystem to multi filesystem.
222

223
        Parameters:
224
        - name: str, filesystem name
225
        - fs: FS, filesystem to add
226
        - write: bool, allow writes to this filesystem
227
        - priority: int, filesystem priority (higher = checked first)
228
        """
229
    
230
    def remove_fs(self, name: str) -> FS:
231
        """
232
        Remove filesystem by name.
233

234
        Parameters:
235
        - name: str, filesystem name
236

237
        Returns:
238
        FS: Removed filesystem
239
        """
240
```
241

242
### Wrapper Filesystems
243

244
Base classes and common wrappers for extending filesystem functionality.
245

246
```python { .api }
247
class WrapFS(FS):
248
    """Base class for filesystem wrappers."""
249
    
250
    def __init__(self, wrap_fs: FS) -> None:
251
        """
252
        Create wrapper filesystem.
253

254
        Parameters:
255
        - wrap_fs: FS, filesystem to wrap
256
        """
257

258
class ReadOnlyFS(WrapFS):
259
    """Read-only filesystem wrapper."""
260
    pass
261

262
class CachingFS(WrapFS):
263
    """Caching filesystem wrapper."""
264
    
265
    def __init__(self, wrap_fs: FS, cache_timeout: int = 60) -> None:
266
        """
267
        Create caching filesystem.
268

269
        Parameters:
270
        - wrap_fs: FS, filesystem to wrap
271
        - cache_timeout: int, cache timeout in seconds
272
        """
273
```
274

275
## Usage Examples
276

277
Creating different filesystem types:
278

279
```python
280
from fs.osfs import OSFS
281
from fs.memoryfs import MemoryFS
282
from fs.zipfs import ZipFS
283
from fs.tempfs import TempFS
284

285
# Local directory filesystem
286
home_fs = OSFS('~', create=True)
287

288
# Memory filesystem
289
mem_fs = MemoryFS()
290

291
# ZIP archive filesystem
292
with ZipFS('archive.zip', write=True) as zip_fs:
293
    zip_fs.writetext('hello.txt', 'Hello World!')
294

295
# Temporary filesystem (auto-cleanup)
296
with TempFS() as temp_fs:
297
    temp_fs.writetext('temp.txt', 'Temporary data')
298
    # Automatically cleaned up on exit
299

300
# Application data filesystem
301
from fs.appfs import AppFS
302
app_fs = AppFS('MyApp', author='MyCompany', version='1.0')
303
```
304

305
Mounting multiple filesystems:
306

307
```python
308
from fs.mountfs import MountFS
309
from fs.osfs import OSFS
310
from fs.memoryfs import MemoryFS
311

312
mount_fs = MountFS()
313
mount_fs.mount('home', OSFS('~'))
314
mount_fs.mount('temp', MemoryFS())
315

316
# Access files through mount points
317
mount_fs.writetext('temp/cache.txt', 'Cached data')
318
mount_fs.copy('home/document.txt', 'temp/backup.txt')
319
```
320

321
## Types
322

323
```python { .api }
324
from typing import Union, IO, Optional
325

326
# Archive compression types
327
CompressionType = Union['deflate', 'stored', 'bzip2', 'lzma']  # ZIP
328
TarCompressionType = Union['gz', 'bz2', 'xz', None]  # TAR
329
```