0
# Filesystem Management
1

2
Create, open, and manage filesystem instances using URLs or direct instantiation. The opener system provides a unified way to access different filesystem types through URL-style strings.
3

4
## Capabilities
5

6
### Opening Filesystems
7

8
Open filesystems using URL-style strings that specify the filesystem type and location.
9

10
```python { .api }
11
def open_fs(fs_url: str, writeable: bool = False, create: bool = False, cwd: str = ".", default_protocol: str = "osfs") -> FS:
12
    """
13
    Open a filesystem from a URL.
14

15
    Parameters:
16
    - fs_url: str, filesystem URL (e.g., '.', 'mem://', 'zip://archive.zip')
17
    - writeable: bool, open filesystem in writeable mode (default: False)
18
    - create: bool, create filesystem if it doesn't exist (default: False)
19
    - cwd: str, current working directory for relative paths (default: ".")
20
    - default_protocol: str, protocol to use if none specified (default: "osfs")
21

22
    Returns:
23
    FS: Filesystem instance
24

25
    Raises:
26
    - FSError: If filesystem cannot be opened
27
    - UnsupportedProtocol: If URL scheme is not supported
28
    """
29
```
30

31
### URL Parsing
32

33
Parse filesystem URLs into their components for analysis or custom processing.
34

35
```python { .api }
36
def parse(fs_url: str) -> ParsedURL:
37
    """
38
    Parse a filesystem URL into components.
39

40
    Parameters:
41
    - fs_url: str, filesystem URL to parse
42

43
    Returns:
44
    ParsedURL: Parsed URL components (protocol, path, params)
45
    """
46
```
47

48
### Filesystem Registry
49

50
Global registry for managing filesystem openers and their associated URL schemes.
51

52
```python { .api }
53
class Registry:
54
    def open_fs(self, fs_url: str, **kwargs) -> FS: ...
55
    def open(self, fs_url: str, **kwargs) -> FS: ...
56
    def manage_fs(self, fs_url: str, **kwargs): ...  # Context manager
57
    def install(self, opener: Opener) -> None: ...
58
    def get_opener(self, protocol: str) -> Opener: ...
59
```
60

61
### URL Schemes
62

63
Common filesystem URL schemes supported by the opener system:
64

65
- `file://` or `.` - Local filesystem (OSFS)
66
- `mem://` - Memory filesystem (MemoryFS) 
67
- `zip://path/to/file.zip` - ZIP archive filesystem (ZipFS)
68
- `tar://path/to/file.tar` - TAR archive filesystem (TarFS)
69
- `ftp://user:pass@host/path` - FTP filesystem (FTPFS)
70
- `temp://` - Temporary filesystem (TempFS)
71
- `osfs://path` - Operating system filesystem (OSFS)
72

73
### Usage Examples
74

75
Opening different filesystem types:
76

77
```python
78
from fs import open_fs
79

80
# Local directory
81
local_fs = open_fs('.')
82
home_fs = open_fs('~')
83

84
# Memory filesystem
85
mem_fs = open_fs('mem://')
86

87
# ZIP archive (read-only by default)
88
zip_fs = open_fs('zip://data.zip')
89

90
# ZIP archive (writeable)
91
zip_fs = open_fs('zip://data.zip', writeable=True)
92

93
# FTP server
94
ftp_fs = open_fs('ftp://user:pass@example.com/uploads')
95

96
# Temporary directory (auto-cleanup)
97
temp_fs = open_fs('temp://')
98
```
99

100
Using as context manager:
101

102
```python
103
from fs.opener import manage_fs
104

105
with manage_fs('temp://') as temp_fs:
106
    temp_fs.writetext('hello.txt', 'Hello World!')
107
    # Filesystem automatically cleaned up on exit
108
```
109

110
## Types
111

112
```python { .api }
113
class ParsedURL:
114
    protocol: str
115
    username: str
116
    password: str  
117
    resource: str
118
    params: Dict[str, str]
119

120
class Opener:
121
    def open_fs(self, fs_url: str, parse_result: ParsedURL, writeable: bool, create: bool, cwd: str) -> FS: ...
122

123
class UnsupportedProtocol(FSError):
124
    """Protocol not supported by any opener."""
125
    pass
126

127
class ParseError(FSError):
128
    """Failed to parse filesystem URL."""
129
    pass
130

131
registry: Registry  # Global registry instance
132
```