Debian Codegraph @

Lib/pathlib/__init__.py

raw ◀ ▶
1 Debian patch touch this file
1 """Object-oriented filesystem paths.
2
3 This module provides classes to represent abstract paths and concrete
4 paths with operations that have semantics appropriate for different
5 operating systems.
6 """
7
8 import io
9 import operator
10 import os
11 import posixpath
12 import sys
13 from errno import *
14 from glob import _StringGlobber, _no_recurse_symlinks
15 from itertools import chain
16 from stat import S_ISDIR, S_ISREG, S_ISSOCK, S_ISBLK, S_ISCHR, S_ISFIFO
17 from _collections_abc import Sequence
18
19 try:
20 import pwd
21 except ImportError:
22 pwd = None
23 try:
24 import grp
25 except ImportError:
26 grp = None
27
28 from pathlib._os import (
29 PathInfo, DirEntryInfo,
30 ensure_different_files, ensure_distinct_paths,
31 copyfile2, copyfileobj, magic_open, copy_info,
32 )
33
34
35 __all__ = [
36 "UnsupportedOperation",
37 "PurePath", "PurePosixPath", "PureWindowsPath",
38 "Path", "PosixPath", "WindowsPath",
39 ]
40
41
42 class UnsupportedOperation(NotImplementedError):
43 """An exception that is raised when an unsupported operation is attempted.
44 """
45 pass
46
47
48 class _PathParents(Sequence):
49 """This object provides sequence-like access to the logical ancestors
50 of a path. Don't try to construct it yourself."""
51 __slots__ = ('_path', '_drv', '_root', '_tail')
52
53 def __init__(self, path):
54 self._path = path
55 self._drv = path.drive
56 self._root = path.root
57 self._tail = path._tail
58
59 def __len__(self):
60 return len(self._tail)
61
62 def __getitem__(self, idx):
63 if isinstance(idx, slice):
64 return tuple(self[i] for i in range(*idx.indices(len(self))))
65
66 if idx >= len(self) or idx < -len(self):
67 raise IndexError(idx)
68 if idx < 0:
69 idx += len(self)
70 return self._path._from_parsed_parts(self._drv, self._root,
71 self._tail[:-idx - 1])
72
73 def __repr__(self):
74 return "<{}.parents>".format(type(self._path).__name__)
75
76
77 class PurePath:
78 """Base class for manipulating paths without I/O.
79
80 PurePath represents a filesystem path and offers operations which
81 don't imply any actual filesystem I/O. Depending on your system,
82 instantiating a PurePath will return either a PurePosixPath or a
83 PureWindowsPath object. You can also instantiate either of these classes
84 directly, regardless of your system.
85 """
86
87 __slots__ = (
88 # The `_raw_paths` slot stores unjoined string paths. This is set in
89 # the `__init__()` method.
90 '_raw_paths',
91
92 # The `_drv`, `_root` and `_tail_cached` slots store parsed and
93 # normalized parts of the path. They are set when any of the `drive`,
94 # `root` or `_tail` properties are accessed for the first time. The
95 # three-part division corresponds to the result of
96 # `os.path.splitroot()`, except that the tail is further split on path
97 # separators (i.e. it is a list of strings), and that the root and
98 # tail are normalized.
99 '_drv', '_root', '_tail_cached',
100
101 # The `_str` slot stores the string representation of the path,
102 # computed from the drive, root and tail when `__str__()` is called
103 # for the first time. It's used to implement `_str_normcase`
104 '_str',
105
106 # The `_str_normcase_cached` slot stores the string path with
107 # normalized case. It is set when the `_str_normcase` property is
108 # accessed for the first time. It's used to implement `__eq__()`
109 # `__hash__()`, and `_parts_normcase`
110 '_str_normcase_cached',
111
112 # The `_parts_normcase_cached` slot stores the case-normalized
113 # string path after splitting on path separators. It's set when the
114 # `_parts_normcase` property is accessed for the first time. It's used
115 # to implement comparison methods like `__lt__()`.
116 '_parts_normcase_cached',
117
118 # The `_hash` slot stores the hash of the case-normalized string
119 # path. It's set when `__hash__()` is called for the first time.
120 '_hash',
121 )
122 parser = os.path
123
124 def __new__(cls, *args, **kwargs):
125 """Construct a PurePath from one or several strings and or existing
126 PurePath objects. The strings and path objects are combined so as
127 to yield a canonicalized path, which is incorporated into the
128 new PurePath object.
129 """
130 if cls is PurePath:
131 cls = PureWindowsPath if os.name == 'nt' else PurePosixPath
132 return object.__new__(cls)
133
134 def __init__(self, *args):
135 paths = []
136 for arg in args:
137 if isinstance(arg, PurePath):
138 if arg.parser is not self.parser:
139 # GH-103631: Convert separators for backwards compatibility.
140 paths.append(arg.as_posix())
141 else:
142 paths.extend(arg._raw_paths)
143 else:
144 try:
145 path = os.fspath(arg)
146 except TypeError:
147 path = arg
148 if not isinstance(path, str):
149 raise TypeError(
150 "argument should be a str or an os.PathLike "
151 "object where __fspath__ returns a str, "
152 f"not {type(path).__name__!r}")
153 paths.append(path)
154 self._raw_paths = paths
155
156 def with_segments(self, *pathsegments):
157 """Construct a new path object from any number of path-like objects.
158 Subclasses may override this method to customize how new path objects
159 are created from methods like `iterdir()`.
160 """
161 return type(self)(*pathsegments)
162
163 def joinpath(self, *pathsegments):
164 """Combine this path with one or several arguments, and return a
165 new path representing either a subpath (if all arguments are relative
166 paths) or a totally different path (if one of the arguments is
167 anchored).
168 """
169 return self.with_segments(self, *pathsegments)
170
171 def __truediv__(self, key):
172 try:
173 return self.with_segments(self, key)
174 except TypeError:
175 return NotImplemented
176
177 def __rtruediv__(self, key):
178 try:
179 return self.with_segments(key, self)
180 except TypeError:
181 return NotImplemented
182
183 def __reduce__(self):
184 return self.__class__, tuple(self._raw_paths)
185
186 def __repr__(self):
187 return "{}({!r})".format(self.__class__.__name__, self.as_posix())
188
189 def __fspath__(self):
190 return str(self)
191
192 def __bytes__(self):
193 """Return the bytes representation of the path. This is only
194 recommended to use under Unix."""
195 return os.fsencode(self)
196
197 @property
198 def _str_normcase(self):
199 # String with normalized case, for hashing and equality checks
200 try:
201 return self._str_normcase_cached
202 except AttributeError:
203 if self.parser is posixpath:
204 self._str_normcase_cached = str(self)
205 else:
206 self._str_normcase_cached = str(self).lower()
207 return self._str_normcase_cached
208
209 def __hash__(self):
210 try:
211 return self._hash
212 except AttributeError:
213 self._hash = hash(self._str_normcase)
214 return self._hash
215
216 def __eq__(self, other):
217 if not isinstance(other, PurePath):
218 return NotImplemented
219 return self._str_normcase == other._str_normcase and self.parser is other.parser
220
221 @property
222 def _parts_normcase(self):
223 # Cached parts with normalized case, for comparisons.
224 try:
225 return self._parts_normcase_cached
226 except AttributeError:
227 self._parts_normcase_cached = self._str_normcase.split(self.parser.sep)
228 return self._parts_normcase_cached
229
230 def __lt__(self, other):
231 if not isinstance(other, PurePath) or self.parser is not other.parser:
232 return NotImplemented
233 return self._parts_normcase < other._parts_normcase
234
235 def __le__(self, other):
236 if not isinstance(other, PurePath) or self.parser is not other.parser:
237 return NotImplemented
238 return self._parts_normcase <= other._parts_normcase
239
240 def __gt__(self, other):
241 if not isinstance(other, PurePath) or self.parser is not other.parser:
242 return NotImplemented
243 return self._parts_normcase > other._parts_normcase
244
245 def __ge__(self, other):
246 if not isinstance(other, PurePath) or self.parser is not other.parser:
247 return NotImplemented
248 return self._parts_normcase >= other._parts_normcase
249
250 def __str__(self):
251 """Return the string representation of the path, suitable for
252 passing to system calls."""
253 try:
254 return self._str
255 except AttributeError:
256 self._str = self._format_parsed_parts(self.drive, self.root,
257 self._tail) or '.'
258 return self._str
259
260 @classmethod
261 def _format_parsed_parts(cls, drv, root, tail):
262 if drv or root:
263 return drv + root + cls.parser.sep.join(tail)
264 elif tail and cls.parser.splitdrive(tail[0])[0]:
265 tail = ['.'] + tail
266 return cls.parser.sep.join(tail)
267
268 def _from_parsed_parts(self, drv, root, tail):
269 path = self._from_parsed_string(self._format_parsed_parts(drv, root, tail))
270 path._drv = drv
271 path._root = root
272 path._tail_cached = tail
273 return path
274
275 def _from_parsed_string(self, path_str):
276 path = self.with_segments(path_str)
277 path._str = path_str or '.'
278 return path
279
280 @classmethod
281 def _parse_path(cls, path):
282 if not path:
283 return '', '', []
284 sep = cls.parser.sep
285 altsep = cls.parser.altsep
286 if altsep:
287 path = path.replace(altsep, sep)
288 drv, root, rel = cls.parser.splitroot(path)
289 if not root and drv.startswith(sep) and not drv.endswith(sep):
290 drv_parts = drv.split(sep)
291 if len(drv_parts) == 4 and drv_parts[2] not in '?.':
292 # e.g. //server/share
293 root = sep
294 elif len(drv_parts) == 6:
295 # e.g. //?/unc/server/share
296 root = sep
297 return drv, root, [x for x in rel.split(sep) if x and x != '.']
298
299 @classmethod
300 def _parse_pattern(cls, pattern):
301 """Parse a glob pattern to a list of parts. This is much like
302 _parse_path, except:
303
304 - Rather than normalizing and returning the drive and root, we raise
305 NotImplementedError if either are present.
306 - If the path has no real parts, we raise ValueError.
307 - If the path ends in a slash, then a final empty part is added.
308 """
309 drv, root, rel = cls.parser.splitroot(pattern)
310 if root or drv:
311 raise NotImplementedError("Non-relative patterns are unsupported")
312 sep = cls.parser.sep
313 altsep = cls.parser.altsep
314 if altsep:
315 rel = rel.replace(altsep, sep)
316 parts = [x for x in rel.split(sep) if x and x != '.']
317 if not parts:
318 raise ValueError(f"Unacceptable pattern: {str(pattern)!r}")
319 elif rel.endswith(sep):
320 # GH-65238: preserve trailing slash in glob patterns.
321 parts.append('')
322 return parts
323
324 def as_posix(self):
325 """Return the string representation of the path with forward (/)
326 slashes."""
327 return str(self).replace(self.parser.sep, '/')
328
329 @property
330 def _raw_path(self):
331 paths = self._raw_paths
332 if len(paths) == 1:
333 return paths[0]
334 elif paths:
335 # Join path segments from the initializer.
336 return self.parser.join(*paths)
337 else:
338 return ''
339
340 @property
341 def drive(self):
342 """The drive prefix (letter or UNC path), if any."""
343 try:
344 return self._drv
345 except AttributeError:
346 self._drv, self._root, self._tail_cached = self._parse_path(self._raw_path)
347 return self._drv
348
349 @property
350 def root(self):
351 """The root of the path, if any."""
352 try:
353 return self._root
354 except AttributeError:
355 self._drv, self._root, self._tail_cached = self._parse_path(self._raw_path)
356 return self._root
357
358 @property
359 def _tail(self):
360 try:
361 return self._tail_cached
362 except AttributeError:
363 self._drv, self._root, self._tail_cached = self._parse_path(self._raw_path)
364 return self._tail_cached
365
366 @property
367 def anchor(self):
368 """The concatenation of the drive and root, or ''."""
369 return self.drive + self.root
370
371 @property
372 def parts(self):
373 """An object providing sequence-like access to the
374 components in the filesystem path."""
375 if self.drive or self.root:
376 return (self.drive + self.root,) + tuple(self._tail)
377 else:
378 return tuple(self._tail)
379
380 @property
381 def parent(self):
382 """The logical parent of the path."""
383 drv = self.drive
384 root = self.root
385 tail = self._tail
386 if not tail:
387 return self
388 return self._from_parsed_parts(drv, root, tail[:-1])
389
390 @property
391 def parents(self):
392 """A sequence of this path's logical parents."""
393 # The value of this property should not be cached on the path object,
394 # as doing so would introduce a reference cycle.
395 return _PathParents(self)
396
397 @property
398 def name(self):
399 """The final path component, if any."""
400 tail = self._tail
401 if not tail:
402 return ''
403 return tail[-1]
404
405 def with_name(self, name):
406 """Return a new path with the file name changed."""
407 p = self.parser
408 if not name or p.sep in name or (p.altsep and p.altsep in name) or name == '.':
409 raise ValueError(f"Invalid name {name!r}")
410 tail = self._tail.copy()
411 if not tail:
412 raise ValueError(f"{self!r} has an empty name")
413 tail[-1] = name
414 return self._from_parsed_parts(self.drive, self.root, tail)
415
416 def with_stem(self, stem):
417 """Return a new path with the stem changed."""
418 suffix = self.suffix
419 if not suffix:
420 return self.with_name(stem)
421 elif not stem:
422 # If the suffix is non-empty, we can't make the stem empty.
423 raise ValueError(f"{self!r} has a non-empty suffix")
424 else:
425 return self.with_name(stem + suffix)
426
427 def with_suffix(self, suffix):
428 """Return a new path with the file suffix changed. If the path
429 has no suffix, add given suffix. If the given suffix is an empty
430 string, remove the suffix from the path.
431 """
432 stem = self.stem
433 if not stem:
434 # If the stem is empty, we can't make the suffix non-empty.
435 raise ValueError(f"{self!r} has an empty name")
436 elif suffix and not suffix.startswith('.'):
437 raise ValueError(f"Invalid suffix {suffix!r}")
438 else:
439 return self.with_name(stem + suffix)
440
441 @property
442 def stem(self):
443 """The final path component, minus its last suffix."""
444 name = self.name
445 i = name.rfind('.')
446 if i != -1:
447 stem = name[:i]
448 # Stem must contain at least one non-dot character.
449 if stem.lstrip('.'):
450 return stem
451 return name
452
453 @property
454 def suffix(self):
455 """
456 The final component's last suffix, if any.
457
458 This includes the leading period. For example: '.txt'
459 """
460 name = self.name.lstrip('.')
461 i = name.rfind('.')
462 if i != -1:
463 return name[i:]
464 return ''
465
466 @property
467 def suffixes(self):
468 """
469 A list of the final component's suffixes, if any.
470
471 These include the leading periods. For example: ['.tar', '.gz']
472 """
473 return ['.' + ext for ext in self.name.lstrip('.').split('.')[1:]]
474
475 def relative_to(self, other, *, walk_up=False):
476 """Return the relative path to another path identified by the passed
477 arguments. If the operation is not possible (because this is not
478 related to the other path), raise ValueError.
479
480 The *walk_up* parameter controls whether `..` may be used to resolve
481 the path.
482 """
483 if not hasattr(other, 'with_segments'):
484 other = self.with_segments(other)
485 for step, path in enumerate(chain([other], other.parents)):
486 if path == self or path in self.parents:
487 break
488 elif not walk_up:
489 raise ValueError(f"{str(self)!r} is not in the subpath of {str(other)!r}")
490 elif path.name == '..':
491 raise ValueError(f"'..' segment in {str(other)!r} cannot be walked")
492 else:
493 raise ValueError(f"{str(self)!r} and {str(other)!r} have different anchors")
494 parts = ['..'] * step + self._tail[len(path._tail):]
495 return self._from_parsed_parts('', '', parts)
496
497 def is_relative_to(self, other):
498 """Return True if the path is relative to another path or False.
499 """
500 if not hasattr(other, 'with_segments'):
501 other = self.with_segments(other)
502 return other == self or other in self.parents
503
504 def is_absolute(self):
505 """True if the path is absolute (has both a root and, if applicable,
506 a drive)."""
507 if self.parser is posixpath:
508 # Optimization: work with raw paths on POSIX.
509 for path in self._raw_paths:
510 if path.startswith('/'):
511 return True
512 return False
513 return self.parser.isabs(self)
514
515 def is_reserved(self):
516 """Return True if the path contains one of the special names reserved
517 by the system, if any."""
•518 import ntpath
519 import warnings
520 msg = ("pathlib.PurePath.is_reserved() is deprecated and scheduled "
521 "for removal in Python 3.15. Use os.path.isreserved() to "
522 "detect reserved paths on Windows.")
523 warnings._deprecated("pathlib.PurePath.is_reserved", msg, remove=(3, 15))
524 if self.parser is ntpath:
525 return self.parser.isreserved(self)
526 return False
527
528 def as_uri(self):
529 """Return the path as a URI."""
530 import warnings
531 msg = ("pathlib.PurePath.as_uri() is deprecated and scheduled "
532 "for removal in Python 3.19. Use pathlib.Path.as_uri().")
533 warnings._deprecated("pathlib.PurePath.as_uri", msg, remove=(3, 19))
534 if not self.is_absolute():
535 raise ValueError("relative path can't be expressed as a file URI")
536
537 drive = self.drive
538 if len(drive) == 2 and drive[1] == ':':
539 # It's a path on a local drive => 'file:///c:/a/b'
540 prefix = 'file:///' + drive
541 path = self.as_posix()[2:]
542 elif drive:
543 # It's a path on a network drive => 'file://host/share/a/b'
544 prefix = 'file:'
545 path = self.as_posix()
546 else:
547 # It's a posix path => 'file:///etc/hosts'
548 prefix = 'file://'
549 path = str(self)
550 from urllib.parse import quote_from_bytes
551 return prefix + quote_from_bytes(os.fsencode(path))
552
553 def full_match(self, pattern, *, case_sensitive=None):
554 """
555 Return True if this path matches the given glob-style pattern. The
556 pattern is matched against the entire path.
557 """
558 if not hasattr(pattern, 'with_segments'):
559 pattern = self.with_segments(pattern)
560 if case_sensitive is None:
561 case_sensitive = self.parser is posixpath
562
563 # The string representation of an empty path is a single dot ('.'). Empty
564 # paths shouldn't match wildcards, so we change it to the empty string.
565 path = str(self) if self.parts else ''
566 pattern = str(pattern) if pattern.parts else ''
567 globber = _StringGlobber(self.parser.sep, case_sensitive, recursive=True)
568 return globber.compile(pattern)(path) is not None
569
570 def match(self, path_pattern, *, case_sensitive=None):
571 """
572 Return True if this path matches the given pattern. If the pattern is
573 relative, matching is done from the right; otherwise, the entire path
574 is matched. The recursive wildcard '**' is *not* supported by this
575 method.
576 """
577 if not hasattr(path_pattern, 'with_segments'):
578 path_pattern = self.with_segments(path_pattern)
579 if case_sensitive is None:
580 case_sensitive = self.parser is posixpath
581 path_parts = self.parts[::-1]
582 pattern_parts = path_pattern.parts[::-1]
583 if not pattern_parts:
584 raise ValueError("empty pattern")
585 if len(path_parts) < len(pattern_parts):
586 return False
587 if len(path_parts) > len(pattern_parts) and path_pattern.anchor:
588 return False
589 globber = _StringGlobber(self.parser.sep, case_sensitive)
590 for path_part, pattern_part in zip(path_parts, pattern_parts):
591 match = globber.compile(pattern_part)
592 if match(path_part) is None:
593 return False
594 return True
595
596 # Subclassing os.PathLike makes isinstance() checks slower,
597 # which in turn makes Path construction slower. Register instead!
598 os.PathLike.register(PurePath)
599
600
601 class PurePosixPath(PurePath):
602 """PurePath subclass for non-Windows systems.
603
604 On a POSIX system, instantiating a PurePath should return this object.
605 However, you can also instantiate it directly on any system.
606 """
607 parser = posixpath
608 __slots__ = ()
609
610
611 class PureWindowsPath(PurePath):
612 """PurePath subclass for Windows systems.
613
614 On a Windows system, instantiating a PurePath should return this object.
615 However, you can also instantiate it directly on any system.
616 """
•617 import ntpath
618 parser = ntpath
619 __slots__ = ()
620
621
622 class Path(PurePath):
623 """PurePath subclass that can make system calls.
624
625 Path represents a filesystem path but unlike PurePath, also offers
626 methods to do system calls on path objects. Depending on your system,
627 instantiating a Path will return either a PosixPath or a WindowsPath
628 object. You can also instantiate a PosixPath or WindowsPath directly,
629 but cannot instantiate a WindowsPath on a POSIX system or vice versa.
630 """
631 __slots__ = ('_info',)
632
633 def __new__(cls, *args, **kwargs):
634 if cls is Path:
635 cls = WindowsPath if os.name == 'nt' else PosixPath
636 return object.__new__(cls)
637
638 @property
639 def info(self):
640 """
641 A PathInfo object that exposes the file type and other file attributes
642 of this path.
643 """
644 try:
645 return self._info
646 except AttributeError:
647 self._info = PathInfo(self)
648 return self._info
649
650 def stat(self, *, follow_symlinks=True):
651 """
652 Return the result of the stat() system call on this path, like
653 os.stat() does.
654 """
655 return os.stat(self, follow_symlinks=follow_symlinks)
656
657 def lstat(self):
658 """
659 Like stat(), except if the path points to a symlink, the symlink's
660 status information is returned, rather than its target's.
661 """
662 return os.lstat(self)
663
664 def exists(self, *, follow_symlinks=True):
665 """
666 Whether this path exists.
667
668 This method normally follows symlinks; to check whether a symlink exists,
669 add the argument follow_symlinks=False.
670 """
671 if follow_symlinks:
672 return os.path.exists(self)
673 return os.path.lexists(self)
674
675 def is_dir(self, *, follow_symlinks=True):
676 """
677 Whether this path is a directory.
678 """
679 if follow_symlinks:
680 return os.path.isdir(self)
681 try:
682 return S_ISDIR(self.stat(follow_symlinks=follow_symlinks).st_mode)
683 except (OSError, ValueError):
684 return False
685
686 def is_file(self, *, follow_symlinks=True):
687 """
688 Whether this path is a regular file (also True for symlinks pointing
689 to regular files).
690 """
691 if follow_symlinks:
692 return os.path.isfile(self)
693 try:
694 return S_ISREG(self.stat(follow_symlinks=follow_symlinks).st_mode)
695 except (OSError, ValueError):
696 return False
697
698 def is_mount(self):
699 """
700 Check if this path is a mount point
701 """
702 return os.path.ismount(self)
703
704 def is_symlink(self):
705 """
706 Whether this path is a symbolic link.
707 """
708 return os.path.islink(self)
709
710 def is_junction(self):
711 """
712 Whether this path is a junction.
713 """
714 return os.path.isjunction(self)
715
716 def is_block_device(self):
717 """
718 Whether this path is a block device.
719 """
720 try:
721 return S_ISBLK(self.stat().st_mode)
722 except (OSError, ValueError):
723 return False
724
725 def is_char_device(self):
726 """
727 Whether this path is a character device.
728 """
729 try:
730 return S_ISCHR(self.stat().st_mode)
731 except (OSError, ValueError):
732 return False
733
734 def is_fifo(self):
735 """
736 Whether this path is a FIFO.
737 """
738 try:
739 return S_ISFIFO(self.stat().st_mode)
740 except (OSError, ValueError):
741 return False
742
743 def is_socket(self):
744 """
745 Whether this path is a socket.
746 """
747 try:
748 return S_ISSOCK(self.stat().st_mode)
749 except (OSError, ValueError):
750 return False
751
752 def samefile(self, other_path):
753 """Return whether other_path is the same or not as this file
754 (as returned by os.path.samefile()).
755 """
756 st = self.stat()
757 try:
758 other_st = other_path.stat()
759 except AttributeError:
760 other_st = self.with_segments(other_path).stat()
761 return (st.st_ino == other_st.st_ino and
762 st.st_dev == other_st.st_dev)
763
764 def open(self, mode='r', buffering=-1, encoding=None,
765 errors=None, newline=None):
766 """
767 Open the file pointed to by this path and return a file object, as
768 the built-in open() function does.
769 """
770 if "b" not in mode:
771 encoding = io.text_encoding(encoding)
772 return io.open(self, mode, buffering, encoding, errors, newline)
773
774 def read_bytes(self):
775 """
776 Open the file in bytes mode, read it, and close the file.
777 """
778 with self.open(mode='rb', buffering=0) as f:
779 return f.read()
780
781 def read_text(self, encoding=None, errors=None, newline=None):
782 """
783 Open the file in text mode, read it, and close the file.
784 """
785 # Call io.text_encoding() here to ensure any warning is raised at an
786 # appropriate stack level.
787 encoding = io.text_encoding(encoding)
788 with self.open(mode='r', encoding=encoding, errors=errors, newline=newline) as f:
789 return f.read()
790
791 def write_bytes(self, data):
792 """
793 Open the file in bytes mode, write to it, and close the file.
794 """
795 # type-check for the buffer interface before truncating the file
796 view = memoryview(data)
797 with self.open(mode='wb') as f:
798 return f.write(view)
799
800 def write_text(self, data, encoding=None, errors=None, newline=None):
801 """
802 Open the file in text mode, write to it, and close the file.
803 """
804 # Call io.text_encoding() here to ensure any warning is raised at an
805 # appropriate stack level.
806 encoding = io.text_encoding(encoding)
807 if not isinstance(data, str):
808 raise TypeError('data must be str, not %s' %
809 data.__class__.__name__)
810 with self.open(mode='w', encoding=encoding, errors=errors, newline=newline) as f:
811 return f.write(data)
812
813 _remove_leading_dot = operator.itemgetter(slice(2, None))
814 _remove_trailing_slash = operator.itemgetter(slice(-1))
815
816 def _filter_trailing_slash(self, paths):
817 sep = self.parser.sep
818 anchor_len = len(self.anchor)
819 for path_str in paths:
820 if len(path_str) > anchor_len and path_str[-1] == sep:
821 path_str = path_str[:-1]
822 yield path_str
823
824 def _from_dir_entry(self, dir_entry, path_str):
825 path = self.with_segments(path_str)
826 path._str = path_str
827 path._info = DirEntryInfo(dir_entry)
828 return path
829
830 def iterdir(self):
831 """Yield path objects of the directory contents.
832
833 The children are yielded in arbitrary order, and the
834 special entries '.' and '..' are not included.
835 """
836 root_dir = str(self)
837 with os.scandir(root_dir) as scandir_it:
838 entries = list(scandir_it)
839 if root_dir == '.':
840 return (self._from_dir_entry(e, e.name) for e in entries)
841 else:
842 return (self._from_dir_entry(e, e.path) for e in entries)
843
844 def glob(self, pattern, *, case_sensitive=None, recurse_symlinks=False):
845 """Iterate over this subtree and yield all existing files (of any
846 kind, including directories) matching the given relative pattern.
847 """
848 sys.audit("pathlib.Path.glob", self, pattern)
849 if case_sensitive is None:
850 case_sensitive = self.parser is posixpath
851 case_pedantic = False
852 else:
853 # The user has expressed a case sensitivity choice, but we don't
854 # know the case sensitivity of the underlying filesystem, so we
855 # must use scandir() for everything, including non-wildcard parts.
856 case_pedantic = True
857 parts = self._parse_pattern(pattern)
858 recursive = True if recurse_symlinks else _no_recurse_symlinks
859 globber = _StringGlobber(self.parser.sep, case_sensitive, case_pedantic, recursive)
860 select = globber.selector(parts[::-1])
861 root = str(self)
862 paths = select(self.parser.join(root, ''))
863
864 # Normalize results
865 if root == '.':
866 paths = map(self._remove_leading_dot, paths)
867 if parts[-1] == '':
868 paths = map(self._remove_trailing_slash, paths)
869 elif parts[-1] == '**':
870 paths = self._filter_trailing_slash(paths)
871 paths = map(self._from_parsed_string, paths)
872 return paths
873
874 def rglob(self, pattern, *, case_sensitive=None, recurse_symlinks=False):
875 """Recursively yield all existing files (of any kind, including
876 directories) matching the given relative pattern, anywhere in
877 this subtree.
878 """
879 sys.audit("pathlib.Path.rglob", self, pattern)
880 pattern = self.parser.join('**', pattern)
881 return self.glob(pattern, case_sensitive=case_sensitive, recurse_symlinks=recurse_symlinks)
882
883 def walk(self, top_down=True, on_error=None, follow_symlinks=False):
884 """Walk the directory tree from this directory, similar to os.walk()."""
885 sys.audit("pathlib.Path.walk", self, on_error, follow_symlinks)
886 root_dir = str(self)
887 if not follow_symlinks:
888 follow_symlinks = os._walk_symlinks_as_files
889 results = os.walk(root_dir, top_down, on_error, follow_symlinks)
890 for path_str, dirnames, filenames in results:
891 if root_dir == '.':
892 path_str = path_str[2:]
893 yield self._from_parsed_string(path_str), dirnames, filenames
894
895 def absolute(self):
896 """Return an absolute version of this path
897 No normalization or symlink resolution is performed.
898
899 Use resolve() to resolve symlinks and remove '..' segments.
900 """
901 if self.is_absolute():
902 return self
903 if self.root:
904 drive = os.path.splitroot(os.getcwd())[0]
905 return self._from_parsed_parts(drive, self.root, self._tail)
906 if self.drive:
907 # There is a CWD on each drive-letter drive.
908 cwd = os.path.abspath(self.drive)
909 else:
910 cwd = os.getcwd()
911 if not self._tail:
912 # Fast path for "empty" paths, e.g. Path("."), Path("") or Path().
913 # We pass only one argument to with_segments() to avoid the cost
914 # of joining, and we exploit the fact that getcwd() returns a
915 # fully-normalized string by storing it in _str. This is used to
916 # implement Path.cwd().
917 return self._from_parsed_string(cwd)
918 drive, root, rel = os.path.splitroot(cwd)
919 if not rel:
920 return self._from_parsed_parts(drive, root, self._tail)
921 tail = rel.split(self.parser.sep)
922 tail.extend(self._tail)
923 return self._from_parsed_parts(drive, root, tail)
924
925 @classmethod
926 def cwd(cls):
927 """Return a new path pointing to the current working directory."""
928 cwd = os.getcwd()
929 path = cls(cwd)
930 path._str = cwd # getcwd() returns a normalized path
931 return path
932
933 def resolve(self, strict=False):
934 """
935 Make the path absolute, resolving all symlinks on the way and also
936 normalizing it.
937 """
938
939 return self.with_segments(os.path.realpath(self, strict=strict))
940
941 if pwd:
942 def owner(self, *, follow_symlinks=True):
943 """
944 Return the login name of the file owner.
945 """
946 uid = self.stat(follow_symlinks=follow_symlinks).st_uid
947 return pwd.getpwuid(uid).pw_name
948 else:
949 def owner(self, *, follow_symlinks=True):
950 """
951 Return the login name of the file owner.
952 """
953 f = f"{type(self).__name__}.owner()"
954 raise UnsupportedOperation(f"{f} is unsupported on this system")
955
956 if grp:
957 def group(self, *, follow_symlinks=True):
958 """
959 Return the group name of the file gid.
960 """
961 gid = self.stat(follow_symlinks=follow_symlinks).st_gid
962 return grp.getgrgid(gid).gr_name
963 else:
964 def group(self, *, follow_symlinks=True):
965 """
966 Return the group name of the file gid.
967 """
968 f = f"{type(self).__name__}.group()"
969 raise UnsupportedOperation(f"{f} is unsupported on this system")
970
971 if hasattr(os, "readlink"):
972 def readlink(self):
973 """
974 Return the path to which the symbolic link points.
975 """
976 return self.with_segments(os.readlink(self))
977 else:
978 def readlink(self):
979 """
980 Return the path to which the symbolic link points.
981 """
982 f = f"{type(self).__name__}.readlink()"
983 raise UnsupportedOperation(f"{f} is unsupported on this system")
984
985 def touch(self, mode=0o666, exist_ok=True):
986 """
987 Create this file with the given access mode, if it doesn't exist.
988 """
989
990 if exist_ok:
991 # First try to bump modification time
992 # Implementation note: GNU touch uses the UTIME_NOW option of
993 # the utimensat() / futimens() functions.
994 try:
995 os.utime(self, None)
996 except OSError:
997 # Avoid exception chaining
998 pass
999 else:
1000 return
1001 flags = os.O_CREAT | os.O_WRONLY
1002 if not exist_ok:
1003 flags |= os.O_EXCL
1004 fd = os.open(self, flags, mode)
1005 os.close(fd)
1006
1007 def mkdir(self, mode=0o777, parents=False, exist_ok=False):
1008 """
1009 Create a new directory at this given path.
1010 """
1011 try:
1012 os.mkdir(self, mode)
1013 except FileNotFoundError:
1014 if not parents or self.parent == self:
1015 raise
1016 self.parent.mkdir(parents=True, exist_ok=True)
1017 self.mkdir(mode, parents=False, exist_ok=exist_ok)
1018 except OSError:
1019 # Cannot rely on checking for EEXIST, since the operating system
1020 # could give priority to other errors like EACCES or EROFS
1021 if not exist_ok or not self.is_dir():
1022 raise
1023
1024 def chmod(self, mode, *, follow_symlinks=True):
1025 """
1026 Change the permissions of the path, like os.chmod().
1027 """
1028 os.chmod(self, mode, follow_symlinks=follow_symlinks)
1029
1030 def lchmod(self, mode):
1031 """
1032 Like chmod(), except if the path points to a symlink, the symlink's
1033 permissions are changed, rather than its target's.
1034 """
1035 self.chmod(mode, follow_symlinks=False)
1036
1037 def unlink(self, missing_ok=False):
1038 """
1039 Remove this file or link.
1040 If the path is a directory, use rmdir() instead.
1041 """
1042 try:
1043 os.unlink(self)
1044 except FileNotFoundError:
1045 if not missing_ok:
1046 raise
1047
1048 def rmdir(self):
1049 """
1050 Remove this directory. The directory must be empty.
1051 """
1052 os.rmdir(self)
1053
1054 def _delete(self):
1055 """
1056 Delete this file or directory (including all sub-directories).
1057 """
1058 if self.is_symlink() or self.is_junction():
1059 self.unlink()
1060 elif self.is_dir():
1061 # Lazy import to improve module import time
1062 import shutil
1063 shutil.rmtree(self)
1064 else:
1065 self.unlink()
1066
1067 def rename(self, target):
1068 """
1069 Rename this path to the target path.
1070
1071 The target path may be absolute or relative. Relative paths are
1072 interpreted relative to the current working directory, *not* the
1073 directory of the Path object.
1074
1075 Returns the new Path instance pointing to the target path.
1076 """
1077 os.rename(self, target)
1078 if not hasattr(target, 'with_segments'):
1079 target = self.with_segments(target)
1080 return target
1081
1082 def replace(self, target):
1083 """
1084 Rename this path to the target path, overwriting if that path exists.
1085
1086 The target path may be absolute or relative. Relative paths are
1087 interpreted relative to the current working directory, *not* the
1088 directory of the Path object.
1089
1090 Returns the new Path instance pointing to the target path.
1091 """
1092 os.replace(self, target)
1093 if not hasattr(target, 'with_segments'):
1094 target = self.with_segments(target)
1095 return target
1096
1097 def copy(self, target, **kwargs):
1098 """
1099 Recursively copy this file or directory tree to the given destination.
1100 """
1101 if not hasattr(target, 'with_segments'):
1102 target = self.with_segments(target)
1103 ensure_distinct_paths(self, target)
1104 target._copy_from(self, **kwargs)
1105 return target.joinpath() # Empty join to ensure fresh metadata.
1106
1107 def copy_into(self, target_dir, **kwargs):
1108 """
1109 Copy this file or directory tree into the given existing directory.
1110 """
1111 name = self.name
1112 if not name:
1113 raise ValueError(f"{self!r} has an empty name")
1114 elif hasattr(target_dir, 'with_segments'):
1115 target = target_dir / name
1116 else:
1117 target = self.with_segments(target_dir, name)
1118 return self.copy(target, **kwargs)
1119
1120 def _copy_from(self, source, follow_symlinks=True, preserve_metadata=False):
1121 """
1122 Recursively copy the given path to this path.
1123 """
1124 if not follow_symlinks and source.info.is_symlink():
1125 self._copy_from_symlink(source, preserve_metadata)
1126 elif source.info.is_dir():
1127 children = source.iterdir()
1128 os.mkdir(self)
1129 for child in children:
1130 self.joinpath(child.name)._copy_from(
1131 child, follow_symlinks, preserve_metadata)
1132 if preserve_metadata:
1133 copy_info(source.info, self)
1134 else:
1135 self._copy_from_file(source, preserve_metadata)
1136
1137 def _copy_from_file(self, source, preserve_metadata=False):
1138 ensure_different_files(source, self)
1139 with magic_open(source, 'rb') as source_f:
1140 with open(self, 'wb') as target_f:
1141 copyfileobj(source_f, target_f)
1142 if preserve_metadata:
1143 copy_info(source.info, self)
1144
1145 if copyfile2:
1146 # Use fast OS routine for local file copying where available.
1147 _copy_from_file_fallback = _copy_from_file
1148 def _copy_from_file(self, source, preserve_metadata=False):
1149 try:
1150 source = os.fspath(source)
1151 except TypeError:
1152 pass
1153 else:
1154 copyfile2(source, str(self))
1155 return
1156 self._copy_from_file_fallback(source, preserve_metadata)
1157
1158 if os.name == 'nt':
1159 # If a directory-symlink is copied *before* its target, then
1160 # os.symlink() incorrectly creates a file-symlink on Windows. Avoid
1161 # this by passing *target_is_dir* to os.symlink() on Windows.
1162 def _copy_from_symlink(self, source, preserve_metadata=False):
1163 os.symlink(str(source.readlink()), self, source.info.is_dir())
1164 if preserve_metadata:
1165 copy_info(source.info, self, follow_symlinks=False)
1166 else:
1167 def _copy_from_symlink(self, source, preserve_metadata=False):
1168 os.symlink(str(source.readlink()), self)
1169 if preserve_metadata:
1170 copy_info(source.info, self, follow_symlinks=False)
1171
1172 def move(self, target):
1173 """
1174 Recursively move this file or directory tree to the given destination.
1175 """
1176 # Use os.replace() if the target is os.PathLike and on the same FS.
1177 try:
1178 target = self.with_segments(target)
1179 except TypeError:
1180 pass
1181 else:
1182 ensure_different_files(self, target)
1183 try:
1184 os.replace(self, target)
1185 except OSError as err:
1186 if err.errno != EXDEV:
1187 raise
1188 else:
1189 return target.joinpath() # Empty join to ensure fresh metadata.
1190 # Fall back to copy+delete.
1191 target = self.copy(target, follow_symlinks=False, preserve_metadata=True)
1192 self._delete()
1193 return target
1194
1195 def move_into(self, target_dir):
1196 """
1197 Move this file or directory tree into the given existing directory.
1198 """
1199 name = self.name
1200 if not name:
1201 raise ValueError(f"{self!r} has an empty name")
1202 elif hasattr(target_dir, 'with_segments'):
1203 target = target_dir / name
1204 else:
1205 target = self.with_segments(target_dir, name)
1206 return self.move(target)
1207
1208 if hasattr(os, "symlink"):
1209 def symlink_to(self, target, target_is_directory=False):
1210 """
1211 Make this path a symlink pointing to the target path.
1212 Note the order of arguments (link, target) is the reverse of os.symlink.
1213 """
1214 os.symlink(target, self, target_is_directory)
1215 else:
1216 def symlink_to(self, target, target_is_directory=False):
1217 """
1218 Make this path a symlink pointing to the target path.
1219 Note the order of arguments (link, target) is the reverse of os.symlink.
1220 """
1221 f = f"{type(self).__name__}.symlink_to()"
1222 raise UnsupportedOperation(f"{f} is unsupported on this system")
1223
1224 if hasattr(os, "link"):
1225 def hardlink_to(self, target):
1226 """
1227 Make this path a hard link pointing to the same file as *target*.
1228
1229 Note the order of arguments (self, target) is the reverse of os.link's.
1230 """
1231 os.link(target, self)
1232 else:
1233 def hardlink_to(self, target):
1234 """
1235 Make this path a hard link pointing to the same file as *target*.
1236
1237 Note the order of arguments (self, target) is the reverse of os.link's.
1238 """
1239 f = f"{type(self).__name__}.hardlink_to()"
1240 raise UnsupportedOperation(f"{f} is unsupported on this system")
1241
1242 def expanduser(self):
1243 """ Return a new path with expanded ~ and ~user constructs
1244 (as returned by os.path.expanduser)
1245 """
1246 if (not (self.drive or self.root) and
1247 self._tail and self._tail[0][:1] == '~'):
1248 homedir = os.path.expanduser(self._tail[0])
1249 if homedir[:1] == "~":
1250 raise RuntimeError("Could not determine home directory.")
1251 drv, root, tail = self._parse_path(homedir)
1252 return self._from_parsed_parts(drv, root, tail + self._tail[1:])
1253
1254 return self
1255
1256 @classmethod
1257 def home(cls):
1258 """Return a new path pointing to expanduser('~').
1259 """
1260 homedir = os.path.expanduser("~")
1261 if homedir == "~":
1262 raise RuntimeError("Could not determine home directory.")
1263 return cls(homedir)
1264
1265 def as_uri(self):
1266 """Return the path as a URI."""
1267 if not self.is_absolute():
1268 raise ValueError("relative paths can't be expressed as file URIs")
1269 from urllib.request import pathname2url
1270 return pathname2url(str(self), add_scheme=True)
1271
1272 @classmethod
1273 def from_uri(cls, uri):
1274 """Return a new path from the given 'file' URI."""
1275 from urllib.error import URLError
1276 from urllib.request import url2pathname
1277 try:
1278 path = cls(url2pathname(uri, require_scheme=True))
1279 except URLError as exc:
1280 raise ValueError(exc.reason) from None
1281 if not path.is_absolute():
1282 raise ValueError(f"URI is not absolute: {uri!r}")
1283 return path
1284
1285
1286 class PosixPath(Path, PurePosixPath):
1287 """Path subclass for non-Windows systems.
1288
1289 On a POSIX system, instantiating a Path should return this object.
1290 """
1291 __slots__ = ()
1292
1293 if os.name == 'nt':
1294 def __new__(cls, *args, **kwargs):
1295 raise UnsupportedOperation(
1296 f"cannot instantiate {cls.__name__!r} on your system")
1297
1298 class WindowsPath(Path, PureWindowsPath):
1299 """Path subclass for Windows systems.
1300
1301 On a Windows system, instantiating a Path should return this object.
1302 """
1303 __slots__ = ()
1304
1305 if os.name != 'nt':
1306 def __new__(cls, *args, **kwargs):
1307 raise UnsupportedOperation(
1308 f"cannot instantiate {cls.__name__!r} on your system")