0
# PyFileSystem2 (fs)
1

2
Python's filesystem abstraction layer providing a unified interface for working with different types of filesystems including local directories, ZIP archives, FTP servers, memory filesystems, and more. PyFileSystem2 enables developers to write filesystem code once and have it work seamlessly across various storage backends without modification.
3

4
## Package Information
5

6
- **Package Name**: fs
7
- **Language**: Python
8
- **Installation**: `pip install fs`
9

10
## Core Imports
11

12
```python
13
import fs
14
from fs import open_fs
15
from fs import path
16
```
17

18
For specific filesystem types:
19

20
```python
21
from fs.osfs import OSFS
22
from fs.memoryfs import MemoryFS
23
from fs.zipfs import ZipFS
24
```
25

26
## Basic Usage
27

28
```python
29
from fs import open_fs
30

31
# Open different types of filesystems using URLs
32
local_fs = open_fs('.')
33
memory_fs = open_fs('mem://')
34
zip_fs = open_fs('zip://archive.zip')
35

36
# All filesystems use the same API
37
with local_fs.open('hello.txt', 'w') as f:
38
    f.write('Hello, World!')
39

40
# List directory contents
41
for path in local_fs.listdir('.'):
42
    print(path)
43

44
# Copy files between different filesystem types
45
local_fs.copy('hello.txt', memory_fs, 'hello_copy.txt')
46

47
# Walk directory trees
48
for path in local_fs.walk.files():
49
    print(f"File: {path}")
50
```
51

52
## Architecture
53

54
PyFileSystem2 follows a layered architecture:
55

56
- **FS Base Class**: Abstract interface defining the common filesystem API
57
- **Filesystem Implementations**: Concrete implementations for different storage types (local, memory, archives, network)
58
- **Opener System**: URL-based filesystem creation and management
59
- **Utility Modules**: Path manipulation, copying, walking, globbing, and other filesystem operations
60
- **Error Handling**: Comprehensive exception hierarchy for robust error management
61

62
This design enables maximum portability and reusability, allowing filesystem code to work across diverse storage systems while maintaining a consistent, Pythonic API.
63

64
## Capabilities
65

66
### Filesystem Opening and Management
67

68
Create and manage filesystem instances using URLs or direct instantiation. The opener system provides a unified way to work with different filesystem types through URL-style strings.
69

70
```python { .api }
71
def open_fs(fs_url: str, **kwargs) -> FS: ...
72
```
73

74
[Filesystem Management](./filesystem-management.md)
75

76
### Core Filesystem Operations
77

78
Essential filesystem operations including file and directory manipulation, metadata access, and path operations. These operations form the foundation of the FS interface and are available across all filesystem implementations.
79

80
```python { .api }
81
class FS:
82
    def open(self, path: str, mode: str = 'r', **kwargs) -> IO: ...
83
    def exists(self, path: str) -> bool: ...
84
    def isfile(self, path: str) -> bool: ...
85
    def isdir(self, path: str) -> bool: ...
86
    def listdir(self, path: str = '.') -> List[str]: ...
87
    def makedir(self, path: str, **kwargs) -> SubFS: ...
88
    def remove(self, path: str) -> None: ...
89
    def removedir(self, path: str) -> None: ...
90
```
91

92
[Core Operations](./core-operations.md)
93

94
### Filesystem Implementations
95

96
Concrete filesystem implementations for different storage backends including local directories, memory filesystems, archives, and network filesystems.
97

98
```python { .api }
99
class OSFS(FS): ...
100
class MemoryFS(FS): ...
101
class ZipFS(FS): ...
102
class TarFS(FS): ...
103
class FTPFS(FS): ...
104
class TempFS(FS): ...
105
```
106

107
[Filesystem Types](./filesystem-types.md)
108

109
### Path Operations
110

111
Platform-agnostic path manipulation utilities that work consistently across different operating systems and filesystem types.
112

113
```python { .api }
114
def join(*paths: str) -> str: ...
115
def split(path: str) -> Tuple[str, str]: ...
116
def dirname(path: str) -> str: ...
117
def basename(path: str) -> str: ...
118
def abspath(path: str) -> str: ...
119
def normpath(path: str) -> str: ...
120
```
121

122
[Path Operations](./path-operations.md)
123

124
### File and Directory Operations
125

126
Advanced file and directory operations including copying, moving, walking directory trees, and pattern matching.
127

128
```python { .api }
129
def copy_file(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str) -> None: ...
130
def copy_dir(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str) -> None: ...
131
def move_file(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str) -> None: ...
132
def walk(fs: FS, path: str = '/') -> Iterator[Tuple[str, List[str], List[str]]]: ...
133
```
134

135
[File Operations](./file-operations.md)
136

137
### Error Handling
138

139
Comprehensive exception hierarchy providing specific error types for different filesystem operation failures.
140

141
```python { .api }
142
class FSError(Exception): ...
143
class ResourceNotFound(FSError): ...
144
class ResourceExists(FSError): ...
145
class DirectoryExpected(FSError): ...
146
class FileExpected(FSError): ...
147
class PermissionDenied(FSError): ...
148
```
149

150
[Error Handling](./error-handling.md)