0
# Path Operations
1

2
Platform-agnostic path manipulation utilities that work consistently across different operating systems and filesystem types. PyFileSystem2 uses forward slashes as path separators internally, ensuring compatibility across platforms.
3

4
## Capabilities
5

6
### Path Joining and Splitting
7

8
Combine and separate path components in a platform-independent way.
9

10
```python { .api }
11
def join(*paths: str) -> str:
12
    """
13
    Join path components with forward slashes.
14

15
    Parameters:
16
    - *paths: str, path components to join
17

18
    Returns:
19
    str: Joined path
20

21
    Example:
22
    join('home', 'user', 'documents') -> 'home/user/documents'
23
    """
24

25
def split(path: str) -> Tuple[str, str]:
26
    """
27
    Split path into directory and filename.
28

29
    Parameters:
30
    - path: str, path to split
31

32
    Returns:
33
    Tuple[str, str]: (directory, filename)
34

35
    Example:
36
    split('home/user/file.txt') -> ('home/user', 'file.txt')
37
    """
38

39
def splitext(path: str) -> Tuple[str, str]:
40
    """
41
    Split path into base and extension.
42

43
    Parameters:
44
    - path: str, path to split
45

46
    Returns:
47
    Tuple[str, str]: (base, extension)
48

49
    Example:
50
    splitext('file.txt') -> ('file', '.txt')
51
    """
52

53
def parts(path: str) -> List[str]:
54
    """
55
    Split path into individual components.
56

57
    Parameters:
58
    - path: str, path to split
59

60
    Returns:
61
    List[str]: Path components
62

63
    Example:
64
    parts('home/user/documents') -> ['home', 'user', 'documents']
65
    """
66
```
67

68
### Path Components
69

70
Extract directory and filename components from paths.
71

72
```python { .api }
73
def dirname(path: str) -> str:
74
    """
75
    Get directory portion of path.
76

77
    Parameters:
78
    - path: str, input path
79

80
    Returns:
81
    str: Directory portion
82

83
    Example:
84
    dirname('home/user/file.txt') -> 'home/user'
85
    """
86

87
def basename(path: str) -> str:
88
    """
89
    Get filename portion of path.
90

91
    Parameters:
92
    - path: str, input path
93

94
    Returns:
95
    str: Filename portion
96

97
    Example:
98
    basename('home/user/file.txt') -> 'file.txt'
99
    """
100
```
101

102
### Path Normalization
103

104
Clean and standardize path format for consistent handling.
105

106
```python { .api }
107
def abspath(path: str) -> str:
108
    """
109
    Convert path to absolute form.
110

111
    Parameters:
112
    - path: str, input path
113

114
    Returns:
115
    str: Absolute path
116

117
    Example:
118
    abspath('./file.txt') -> '/current/dir/file.txt'
119
    """
120

121
def normpath(path: str) -> str:
122
    """
123
    Normalize path by removing redundant separators and references.
124

125
    Parameters:
126
    - path: str, input path
127

128
    Returns:
129
    str: Normalized path
130

131
    Example:
132
    normpath('home//user/../user/file.txt') -> 'home/user/file.txt'
133
    """
134

135
def relpath(path: str, start: str = '/') -> str:
136
    """
137
    Get relative path from start directory.
138

139
    Parameters:
140
    - path: str, target path
141
    - start: str, starting directory
142

143
    Returns:
144
    str: Relative path
145

146
    Example:
147
    relpath('/home/user/file.txt', '/home') -> 'user/file.txt'
148
    """
149
```
150

151
### Path Analysis
152

153
Analyze path properties and relationships.
154

155
```python { .api }
156
def isabs(path: str) -> bool:
157
    """
158
    Check if path is absolute.
159

160
    Parameters:
161
    - path: str, path to check
162

163
    Returns:
164
    bool: True if path is absolute
165

166
    Example:
167
    isabs('/home/user') -> True
168
    isabs('user/file') -> False
169
    """
170

171
def isroot(path: str) -> bool:
172
    """
173
    Check if path is root directory.
174

175
    Parameters:
176
    - path: str, path to check
177

178
    Returns:
179
    bool: True if path is root
180

181
    Example:
182
    isroot('/') -> True
183
    isroot('/home') -> False
184
    """
185

186
def isdotfile(path: str) -> bool:
187
    """
188
    Check if path is a dot file (hidden file).
189

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

193
    Returns:
194
    bool: True if filename starts with dot
195

196
    Example:
197
    isdotfile('.hidden') -> True
198
    isdotfile('visible.txt') -> False
199
    """
200

201
def commonpath(paths: List[str]) -> str:
202
    """
203
    Get common path prefix for multiple paths.
204

205
    Parameters:
206
    - paths: List[str], paths to compare
207

208
    Returns:
209
    str: Common path prefix
210

211
    Example:
212
    commonpath(['/home/user/a', '/home/user/b']) -> '/home/user'
213
    """
214
```
215

216
### Path Traversal
217

218
Iterate through path components and directory hierarchies.
219

220
```python { .api }
221
def iteratepath(path: str, reverse: bool = False) -> Iterator[str]:
222
    """
223
    Iterate over path components.
224

225
    Parameters:
226
    - path: str, path to iterate
227
    - reverse: bool, iterate from leaf to root
228

229
    Returns:
230
    Iterator[str]: Path components
231

232
    Example:
233
    list(iteratepath('home/user/file')) -> ['home', 'home/user', 'home/user/file']
234
    """
235

236
def recursepath(path: str, reverse: bool = False) -> Iterator[str]:
237
    """
238
    Recursively iterate through directory path components.
239

240
    Parameters:
241
    - path: str, directory path
242
    - reverse: bool, iterate from deepest to shallowest
243

244
    Returns:
245
    Iterator[str]: Directory paths
246

247
    Example:
248
    list(recursepath('a/b/c')) -> ['a', 'a/b', 'a/b/c']
249
    """
250
```
251

252
### Path Utilities
253

254
Additional utilities for path manipulation and formatting.
255

256
```python { .api }
257
def forcedir(path: str) -> str:
258
    """
259
    Ensure path ends with directory separator.
260

261
    Parameters:
262
    - path: str, input path
263

264
    Returns:
265
    str: Path ending with separator
266

267
    Example:
268
    forcedir('home/user') -> 'home/user/'
269
    """
270

271
def frombase(path: str, base: str) -> str:
272
    """
273
    Convert path relative to base directory.
274

275
    Parameters:
276
    - path: str, full path
277
    - base: str, base directory
278

279
    Returns:
280
    str: Path relative to base
281

282
    Example:
283
    frombase('/home/user/file.txt', '/home') -> 'user/file.txt'
284
    """
285

286
def iswildcard(path: str) -> bool:
287
    """
288
    Check if path contains wildcard characters.
289

290
    Parameters:
291
    - path: str, path to check
292

293
    Returns:
294
    bool: True if path contains wildcards (* or ?)
295

296
    Example:
297
    iswildcard('*.txt') -> True
298
    iswildcard('file.txt') -> False
299
    """
300
```
301

302
## Usage Examples
303

304
Basic path operations:
305

306
```python
307
from fs import path
308

309
# Join path components
310
file_path = path.join('home', 'user', 'documents', 'file.txt')
311
# Result: 'home/user/documents/file.txt'
312

313
# Split path
314
directory, filename = path.split(file_path)
315
# Result: ('home/user/documents', 'file.txt')
316

317
# Get components
318
base, ext = path.splitext(filename)
319
# Result: ('file', '.txt')
320

321
# Normalize paths
322
clean_path = path.normpath('home//user/../user/./file.txt')
323
# Result: 'home/user/file.txt'
324
```
325

326
Working with path hierarchies:
327

328
```python
329
from fs import path
330

331
# Iterate through path components
332
for component in path.iteratepath('home/user/documents'):
333
    print(component)
334
# Output: 'home', 'home/user', 'home/user/documents'
335

336
# Get common path
337
common = path.commonpath([
338
    'home/user/docs/file1.txt',
339
    'home/user/docs/file2.txt',
340
    'home/user/pics/image.jpg'
341
])
342
# Result: 'home/user'
343
```
344

345
Path analysis:
346

347
```python
348
from fs import path
349

350
# Check path properties  
351
print(path.isabs('/home/user'))        # True
352
print(path.isabs('user/file'))         # False
353
print(path.isdotfile('.bashrc'))       # True
354
print(path.iswildcard('*.txt'))        # True
355
```
356

357
## Types
358

359
```python { .api }
360
from typing import List, Tuple, Iterator
361

362
# Path types are generally strings, but some functions return tuples or lists
363
PathComponents = List[str]
364
PathTuple = Tuple[str, str]
365
```