Debian Codegraph @

Lib/pathlib/types.py

raw
1 """
2 Protocols for supporting classes in pathlib.
3 """
4
5 # This module also provides abstract base classes for rich path objects.
6 # These ABCs are a *private* part of the Python standard library, but they're
7 # made available as a PyPI package called "pathlib-abc". It's possible they'll
8 # become an official part of the standard library in future.
9 #
10 # Three ABCs are provided -- _JoinablePath, _ReadablePath and _WritablePath
11
12
13 from abc import ABC, abstractmethod
14 from glob import _PathGlobber
15 from io import text_encoding
16 from pathlib._os import magic_open, ensure_distinct_paths, ensure_different_files, copyfileobj
17 from pathlib import PurePath, Path
18 from typing import Optional, Protocol, runtime_checkable
19
20
21 def _explode_path(path, split):
22 """
23 Split the path into a 2-tuple (anchor, parts), where *anchor* is the
24 uppermost parent of the path (equivalent to path.parents[-1]), and
25 *parts* is a reversed list of parts following the anchor.
26 """
27 parent, name = split(path)
28 names = []
29 while path != parent:
30 names.append(name)
31 path = parent
32 parent, name = split(path)
33 return path, names
34
35
36 @runtime_checkable
37 class _PathParser(Protocol):
38 """Protocol for path parsers, which do low-level path manipulation.
39
40 Path parsers provide a subset of the os.path API, specifically those
41 functions needed to provide JoinablePath functionality. Each JoinablePath
42 subclass references its path parser via a 'parser' class attribute.
43 """
44
45 sep: str
46 altsep: Optional[str]
47 def split(self, path: str) -> tuple[str, str]: ...
48 def splitext(self, path: str) -> tuple[str, str]: ...
49 def normcase(self, path: str) -> str: ...
50
51
52 @runtime_checkable
53 class PathInfo(Protocol):
54 """Protocol for path info objects, which support querying the file type.
55 Methods may return cached results.
56 """
57 def exists(self, *, follow_symlinks: bool = True) -> bool: ...
58 def is_dir(self, *, follow_symlinks: bool = True) -> bool: ...
59 def is_file(self, *, follow_symlinks: bool = True) -> bool: ...
60 def is_symlink(self) -> bool: ...
61
62
63 class _JoinablePath(ABC):
64 """Abstract base class for pure path objects.
65
66 This class *does not* provide several magic methods that are defined in
67 its implementation PurePath. They are: __init__, __fspath__, __bytes__,
68 __reduce__, __hash__, __eq__, __lt__, __le__, __gt__, __ge__.
69 """
70 __slots__ = ()
71
72 @property
73 @abstractmethod
74 def parser(self):
75 """Implementation of pathlib._types.Parser used for low-level path
76 parsing and manipulation.
77 """
78 raise NotImplementedError
79
80 @abstractmethod
81 def with_segments(self, *pathsegments):
82 """Construct a new path object from any number of path-like objects.
83 Subclasses may override this method to customize how new path objects
84 are created from methods like `iterdir()`.
85 """
86 raise NotImplementedError
87
88 @abstractmethod
89 def __str__(self):
90 """Return the string representation of the path, suitable for
91 passing to system calls."""
92 raise NotImplementedError
93
94 @property
95 def anchor(self):
96 """The concatenation of the drive and root, or ''."""
97 return _explode_path(str(self), self.parser.split)[0]
98
99 @property
100 def name(self):
101 """The final path component, if any."""
102 return self.parser.split(str(self))[1]
103
104 @property
105 def suffix(self):
106 """
107 The final component's last suffix, if any.
108
109 This includes the leading period. For example: '.txt'
110 """
111 return self.parser.splitext(self.name)[1]
112
113 @property
114 def suffixes(self):
115 """
116 A list of the final component's suffixes, if any.
117
118 These include the leading periods. For example: ['.tar', '.gz']
119 """
120 split = self.parser.splitext
121 stem, suffix = split(self.name)
122 suffixes = []
123 while suffix:
124 suffixes.append(suffix)
125 stem, suffix = split(stem)
126 return suffixes[::-1]
127
128 @property
129 def stem(self):
130 """The final path component, minus its last suffix."""
131 return self.parser.splitext(self.name)[0]
132
133 def with_name(self, name):
134 """Return a new path with the file name changed."""
135 split = self.parser.split
136 if split(name)[0]:
137 raise ValueError(f"Invalid name {name!r}")
138 path = str(self)
139 path = path.removesuffix(split(path)[1]) + name
140 return self.with_segments(path)
141
142 def with_stem(self, stem):
143 """Return a new path with the stem changed."""
144 suffix = self.suffix
145 if not suffix:
146 return self.with_name(stem)
147 elif not stem:
148 # If the suffix is non-empty, we can't make the stem empty.
149 raise ValueError(f"{self!r} has a non-empty suffix")
150 else:
151 return self.with_name(stem + suffix)
152
153 def with_suffix(self, suffix):
154 """Return a new path with the file suffix changed. If the path
155 has no suffix, add given suffix. If the given suffix is an empty
156 string, remove the suffix from the path.
157 """
158 stem = self.stem
159 if not stem:
160 # If the stem is empty, we can't make the suffix non-empty.
161 raise ValueError(f"{self!r} has an empty name")
162 elif suffix and not suffix.startswith('.'):
163 raise ValueError(f"Invalid suffix {suffix!r}")
164 else:
165 return self.with_name(stem + suffix)
166
167 @property
168 def parts(self):
169 """An object providing sequence-like access to the
170 components in the filesystem path."""
171 anchor, parts = _explode_path(str(self), self.parser.split)
172 if anchor:
173 parts.append(anchor)
174 return tuple(reversed(parts))
175
176 def joinpath(self, *pathsegments):
177 """Combine this path with one or several arguments, and return a
178 new path representing either a subpath (if all arguments are relative
179 paths) or a totally different path (if one of the arguments is
180 anchored).
181 """
182 return self.with_segments(str(self), *pathsegments)
183
184 def __truediv__(self, key):
185 try:
186 return self.with_segments(str(self), key)
187 except TypeError:
188 return NotImplemented
189
190 def __rtruediv__(self, key):
191 try:
192 return self.with_segments(key, str(self))
193 except TypeError:
194 return NotImplemented
195
196 @property
197 def parent(self):
198 """The logical parent of the path."""
199 path = str(self)
200 parent = self.parser.split(path)[0]
201 if path != parent:
202 return self.with_segments(parent)
203 return self
204
205 @property
206 def parents(self):
207 """A sequence of this path's logical parents."""
208 split = self.parser.split
209 path = str(self)
210 parent = split(path)[0]
211 parents = []
212 while path != parent:
213 parents.append(self.with_segments(parent))
214 path = parent
215 parent = split(path)[0]
216 return tuple(parents)
217
218 def full_match(self, pattern):
219 """
220 Return True if this path matches the given glob-style pattern. The
221 pattern is matched against the entire path.
222 """
223 case_sensitive = self.parser.normcase('Aa') == 'Aa'
224 globber = _PathGlobber(self.parser.sep, case_sensitive, recursive=True)
225 match = globber.compile(pattern, altsep=self.parser.altsep)
226 return match(str(self)) is not None
227
228
229 class _ReadablePath(_JoinablePath):
230 """Abstract base class for readable path objects.
231
232 The Path class implements this ABC for local filesystem paths. Users may
233 create subclasses to implement readable virtual filesystem paths, such as
234 paths in archive files or on remote storage systems.
235 """
236 __slots__ = ()
237
238 @property
239 @abstractmethod
240 def info(self):
241 """
242 A PathInfo object that exposes the file type and other file attributes
243 of this path.
244 """
245 raise NotImplementedError
246
247 @abstractmethod
248 def __open_rb__(self, buffering=-1):
249 """
250 Open the file pointed to by this path for reading in binary mode and
251 return a file object, like open(mode='rb').
252 """
253 raise NotImplementedError
254
255 def read_bytes(self):
256 """
257 Open the file in bytes mode, read it, and close the file.
258 """
259 with magic_open(self, mode='rb', buffering=0) as f:
260 return f.read()
261
262 def read_text(self, encoding=None, errors=None, newline=None):
263 """
264 Open the file in text mode, read it, and close the file.
265 """
266 # Call io.text_encoding() here to ensure any warning is raised at an
267 # appropriate stack level.
268 encoding = text_encoding(encoding)
269 with magic_open(self, mode='r', encoding=encoding, errors=errors, newline=newline) as f:
270 return f.read()
271
272 @abstractmethod
273 def iterdir(self):
274 """Yield path objects of the directory contents.
275
276 The children are yielded in arbitrary order, and the
277 special entries '.' and '..' are not included.
278 """
279 raise NotImplementedError
280
281 def glob(self, pattern, *, recurse_symlinks=True):
282 """Iterate over this subtree and yield all existing files (of any
283 kind, including directories) matching the given relative pattern.
284 """
285 anchor, parts = _explode_path(pattern, self.parser.split)
286 if anchor:
287 raise NotImplementedError("Non-relative patterns are unsupported")
288 elif not parts:
289 raise ValueError(f"Unacceptable pattern: {pattern!r}")
290 elif not recurse_symlinks:
291 raise NotImplementedError("recurse_symlinks=False is unsupported")
292 case_sensitive = self.parser.normcase('Aa') == 'Aa'
293 globber = _PathGlobber(self.parser.sep, case_sensitive, recursive=True)
294 select = globber.selector(parts)
295 return select(self.joinpath(''))
296
297 def walk(self, top_down=True, on_error=None, follow_symlinks=False):
298 """Walk the directory tree from this directory, similar to os.walk()."""
299 paths = [self]
300 while paths:
301 path = paths.pop()
302 if isinstance(path, tuple):
303 yield path
304 continue
305 dirnames = []
306 filenames = []
307 if not top_down:
308 paths.append((path, dirnames, filenames))
309 try:
310 for child in path.iterdir():
311 if child.info.is_dir(follow_symlinks=follow_symlinks):
312 if not top_down:
313 paths.append(child)
314 dirnames.append(child.name)
315 else:
316 filenames.append(child.name)
317 except OSError as error:
318 if on_error is not None:
319 on_error(error)
320 if not top_down:
321 while not isinstance(paths.pop(), tuple):
322 pass
323 continue
324 if top_down:
325 yield path, dirnames, filenames
326 paths += [path.joinpath(d) for d in reversed(dirnames)]
327
328 @abstractmethod
329 def readlink(self):
330 """
331 Return the path to which the symbolic link points.
332 """
333 raise NotImplementedError
334
335 def copy(self, target, **kwargs):
336 """
337 Recursively copy this file or directory tree to the given destination.
338 """
339 ensure_distinct_paths(self, target)
340 target._copy_from(self, **kwargs)
341 return target.joinpath() # Empty join to ensure fresh metadata.
342
343 def copy_into(self, target_dir, **kwargs):
344 """
345 Copy this file or directory tree into the given existing directory.
346 """
347 name = self.name
348 if not name:
349 raise ValueError(f"{self!r} has an empty name")
350 return self.copy(target_dir / name, **kwargs)
351
352
353 class _WritablePath(_JoinablePath):
354 """Abstract base class for writable path objects.
355
356 The Path class implements this ABC for local filesystem paths. Users may
357 create subclasses to implement writable virtual filesystem paths, such as
358 paths in archive files or on remote storage systems.
359 """
360 __slots__ = ()
361
362 @abstractmethod
363 def symlink_to(self, target, target_is_directory=False):
364 """
365 Make this path a symlink pointing to the target path.
366 Note the order of arguments (link, target) is the reverse of os.symlink.
367 """
368 raise NotImplementedError
369
370 @abstractmethod
371 def mkdir(self):
372 """
373 Create a new directory at this given path.
374 """
375 raise NotImplementedError
376
377 @abstractmethod
378 def __open_wb__(self, buffering=-1):
379 """
380 Open the file pointed to by this path for writing in binary mode and
381 return a file object, like open(mode='wb').
382 """
383 raise NotImplementedError
384
385 def write_bytes(self, data):
386 """
387 Open the file in bytes mode, write to it, and close the file.
388 """
389 # type-check for the buffer interface before truncating the file
390 view = memoryview(data)
391 with magic_open(self, mode='wb') as f:
392 return f.write(view)
393
394 def write_text(self, data, encoding=None, errors=None, newline=None):
395 """
396 Open the file in text mode, write to it, and close the file.
397 """
398 # Call io.text_encoding() here to ensure any warning is raised at an
399 # appropriate stack level.
400 encoding = text_encoding(encoding)
401 if not isinstance(data, str):
402 raise TypeError('data must be str, not %s' %
403 data.__class__.__name__)
404 with magic_open(self, mode='w', encoding=encoding, errors=errors, newline=newline) as f:
405 return f.write(data)
406
407 def _copy_from(self, source, follow_symlinks=True):
408 """
409 Recursively copy the given path to this path.
410 """
411 stack = [(source, self)]
412 while stack:
413 src, dst = stack.pop()
414 if not follow_symlinks and src.info.is_symlink():
415 dst.symlink_to(str(src.readlink()), src.info.is_dir())
416 elif src.info.is_dir():
417 children = src.iterdir()
418 dst.mkdir()
419 for child in children:
420 stack.append((child, dst.joinpath(child.name)))
421 else:
422 ensure_different_files(src, dst)
423 with magic_open(src, 'rb') as source_f:
424 with magic_open(dst, 'wb') as target_f:
425 copyfileobj(source_f, target_f)
426
427
428 _JoinablePath.register(PurePath)
429 _ReadablePath.register(Path)
430 _WritablePath.register(Path)