1 2:mod:`pathlib` --- Object-oriented filesystem paths 3=================================================== 4 5.. module:: pathlib 6 :synopsis: Object-oriented filesystem paths 7 8.. versionadded:: 3.4 9 10**Source code:** :source:`Lib/pathlib.py` 11 12.. index:: single: path; operations 13 14-------------- 15 16This module offers classes representing filesystem paths with semantics 17appropriate for different operating systems. Path classes are divided 18between :ref:`pure paths <pure-paths>`, which provide purely computational 19operations without I/O, and :ref:`concrete paths <concrete-paths>`, which 20inherit from pure paths but also provide I/O operations. 21 22.. image:: pathlib-inheritance.png 23 :align: center 24 25If you've never used this module before or just aren't sure which class is 26right for your task, :class:`Path` is most likely what you need. It instantiates 27a :ref:`concrete path <concrete-paths>` for the platform the code is running on. 28 29Pure paths are useful in some special cases; for example: 30 31#. If you want to manipulate Windows paths on a Unix machine (or vice versa). 32 You cannot instantiate a :class:`WindowsPath` when running on Unix, but you 33 can instantiate :class:`PureWindowsPath`. 34#. You want to make sure that your code only manipulates paths without actually 35 accessing the OS. In this case, instantiating one of the pure classes may be 36 useful since those simply don't have any OS-accessing operations. 37 38.. seealso:: 39 :pep:`428`: The pathlib module -- object-oriented filesystem paths. 40 41.. seealso:: 42 For low-level path manipulation on strings, you can also use the 43 :mod:`os.path` module. 44 45 46Basic use 47--------- 48 49Importing the main class:: 50 51 >>> from pathlib import Path 52 53Listing subdirectories:: 54 55 >>> p = Path('.') 56 >>> [x for x in p.iterdir() if x.is_dir()] 57 [PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'), 58 PosixPath('__pycache__'), PosixPath('build')] 59 60Listing Python source files in this directory tree:: 61 62 >>> list(p.glob('**/*.py')) 63 [PosixPath('test_pathlib.py'), PosixPath('setup.py'), 64 PosixPath('pathlib.py'), PosixPath('docs/conf.py'), 65 PosixPath('build/lib/pathlib.py')] 66 67Navigating inside a directory tree:: 68 69 >>> p = Path('/etc') 70 >>> q = p / 'init.d' / 'reboot' 71 >>> q 72 PosixPath('/etc/init.d/reboot') 73 >>> q.resolve() 74 PosixPath('/etc/rc.d/init.d/halt') 75 76Querying path properties:: 77 78 >>> q.exists() 79 True 80 >>> q.is_dir() 81 False 82 83Opening a file:: 84 85 >>> with q.open() as f: f.readline() 86 ... 87 '#!/bin/bash\n' 88 89 90.. _pure-paths: 91 92Pure paths 93---------- 94 95Pure path objects provide path-handling operations which don't actually 96access a filesystem. There are three ways to access these classes, which 97we also call *flavours*: 98 99.. class:: PurePath(*pathsegments) 100 101 A generic class that represents the system's path flavour (instantiating 102 it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`):: 103 104 >>> PurePath('setup.py') # Running on a Unix machine 105 PurePosixPath('setup.py') 106 107 Each element of *pathsegments* can be either a string representing a 108 path segment, an object implementing the :class:`os.PathLike` interface 109 which returns a string, or another path object:: 110 111 >>> PurePath('foo', 'some/path', 'bar') 112 PurePosixPath('foo/some/path/bar') 113 >>> PurePath(Path('foo'), Path('bar')) 114 PurePosixPath('foo/bar') 115 116 When *pathsegments* is empty, the current directory is assumed:: 117 118 >>> PurePath() 119 PurePosixPath('.') 120 121 When several absolute paths are given, the last is taken as an anchor 122 (mimicking :func:`os.path.join`'s behaviour):: 123 124 >>> PurePath('/etc', '/usr', 'lib64') 125 PurePosixPath('/usr/lib64') 126 >>> PureWindowsPath('c:/Windows', 'd:bar') 127 PureWindowsPath('d:bar') 128 129 However, in a Windows path, changing the local root doesn't discard the 130 previous drive setting:: 131 132 >>> PureWindowsPath('c:/Windows', '/Program Files') 133 PureWindowsPath('c:/Program Files') 134 135 Spurious slashes and single dots are collapsed, but double dots (``'..'``) 136 are not, since this would change the meaning of a path in the face of 137 symbolic links:: 138 139 >>> PurePath('foo//bar') 140 PurePosixPath('foo/bar') 141 >>> PurePath('foo/./bar') 142 PurePosixPath('foo/bar') 143 >>> PurePath('foo/../bar') 144 PurePosixPath('foo/../bar') 145 146 (a naïve approach would make ``PurePosixPath('foo/../bar')`` equivalent 147 to ``PurePosixPath('bar')``, which is wrong if ``foo`` is a symbolic link 148 to another directory) 149 150 Pure path objects implement the :class:`os.PathLike` interface, allowing them 151 to be used anywhere the interface is accepted. 152 153 .. versionchanged:: 3.6 154 Added support for the :class:`os.PathLike` interface. 155 156.. class:: PurePosixPath(*pathsegments) 157 158 A subclass of :class:`PurePath`, this path flavour represents non-Windows 159 filesystem paths:: 160 161 >>> PurePosixPath('/etc') 162 PurePosixPath('/etc') 163 164 *pathsegments* is specified similarly to :class:`PurePath`. 165 166.. class:: PureWindowsPath(*pathsegments) 167 168 A subclass of :class:`PurePath`, this path flavour represents Windows 169 filesystem paths:: 170 171 >>> PureWindowsPath('c:/Program Files/') 172 PureWindowsPath('c:/Program Files') 173 174 *pathsegments* is specified similarly to :class:`PurePath`. 175 176Regardless of the system you're running on, you can instantiate all of 177these classes, since they don't provide any operation that does system calls. 178 179 180General properties 181^^^^^^^^^^^^^^^^^^ 182 183Paths are immutable and hashable. Paths of a same flavour are comparable 184and orderable. These properties respect the flavour's case-folding 185semantics:: 186 187 >>> PurePosixPath('foo') == PurePosixPath('FOO') 188 False 189 >>> PureWindowsPath('foo') == PureWindowsPath('FOO') 190 True 191 >>> PureWindowsPath('FOO') in { PureWindowsPath('foo') } 192 True 193 >>> PureWindowsPath('C:') < PureWindowsPath('d:') 194 True 195 196Paths of a different flavour compare unequal and cannot be ordered:: 197 198 >>> PureWindowsPath('foo') == PurePosixPath('foo') 199 False 200 >>> PureWindowsPath('foo') < PurePosixPath('foo') 201 Traceback (most recent call last): 202 File "<stdin>", line 1, in <module> 203 TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath' 204 205 206Operators 207^^^^^^^^^ 208 209The slash operator helps create child paths, similarly to :func:`os.path.join`:: 210 211 >>> p = PurePath('/etc') 212 >>> p 213 PurePosixPath('/etc') 214 >>> p / 'init.d' / 'apache2' 215 PurePosixPath('/etc/init.d/apache2') 216 >>> q = PurePath('bin') 217 >>> '/usr' / q 218 PurePosixPath('/usr/bin') 219 220A path object can be used anywhere an object implementing :class:`os.PathLike` 221is accepted:: 222 223 >>> import os 224 >>> p = PurePath('/etc') 225 >>> os.fspath(p) 226 '/etc' 227 228The string representation of a path is the raw filesystem path itself 229(in native form, e.g. with backslashes under Windows), which you can 230pass to any function taking a file path as a string:: 231 232 >>> p = PurePath('/etc') 233 >>> str(p) 234 '/etc' 235 >>> p = PureWindowsPath('c:/Program Files') 236 >>> str(p) 237 'c:\\Program Files' 238 239Similarly, calling :class:`bytes` on a path gives the raw filesystem path as a 240bytes object, as encoded by :func:`os.fsencode`:: 241 242 >>> bytes(p) 243 b'/etc' 244 245.. note:: 246 Calling :class:`bytes` is only recommended under Unix. Under Windows, 247 the unicode form is the canonical representation of filesystem paths. 248 249 250Accessing individual parts 251^^^^^^^^^^^^^^^^^^^^^^^^^^ 252 253To access the individual "parts" (components) of a path, use the following 254property: 255 256.. data:: PurePath.parts 257 258 A tuple giving access to the path's various components:: 259 260 >>> p = PurePath('/usr/bin/python3') 261 >>> p.parts 262 ('/', 'usr', 'bin', 'python3') 263 264 >>> p = PureWindowsPath('c:/Program Files/PSF') 265 >>> p.parts 266 ('c:\\', 'Program Files', 'PSF') 267 268 (note how the drive and local root are regrouped in a single part) 269 270 271Methods and properties 272^^^^^^^^^^^^^^^^^^^^^^ 273 274.. testsetup:: 275 276 from pathlib import PurePosixPath, PureWindowsPath 277 278Pure paths provide the following methods and properties: 279 280.. data:: PurePath.drive 281 282 A string representing the drive letter or name, if any:: 283 284 >>> PureWindowsPath('c:/Program Files/').drive 285 'c:' 286 >>> PureWindowsPath('/Program Files/').drive 287 '' 288 >>> PurePosixPath('/etc').drive 289 '' 290 291 UNC shares are also considered drives:: 292 293 >>> PureWindowsPath('//host/share/foo.txt').drive 294 '\\\\host\\share' 295 296.. data:: PurePath.root 297 298 A string representing the (local or global) root, if any:: 299 300 >>> PureWindowsPath('c:/Program Files/').root 301 '\\' 302 >>> PureWindowsPath('c:Program Files/').root 303 '' 304 >>> PurePosixPath('/etc').root 305 '/' 306 307 UNC shares always have a root:: 308 309 >>> PureWindowsPath('//host/share').root 310 '\\' 311 312.. data:: PurePath.anchor 313 314 The concatenation of the drive and root:: 315 316 >>> PureWindowsPath('c:/Program Files/').anchor 317 'c:\\' 318 >>> PureWindowsPath('c:Program Files/').anchor 319 'c:' 320 >>> PurePosixPath('/etc').anchor 321 '/' 322 >>> PureWindowsPath('//host/share').anchor 323 '\\\\host\\share\\' 324 325 326.. data:: PurePath.parents 327 328 An immutable sequence providing access to the logical ancestors of 329 the path:: 330 331 >>> p = PureWindowsPath('c:/foo/bar/setup.py') 332 >>> p.parents[0] 333 PureWindowsPath('c:/foo/bar') 334 >>> p.parents[1] 335 PureWindowsPath('c:/foo') 336 >>> p.parents[2] 337 PureWindowsPath('c:/') 338 339 340.. data:: PurePath.parent 341 342 The logical parent of the path:: 343 344 >>> p = PurePosixPath('/a/b/c/d') 345 >>> p.parent 346 PurePosixPath('/a/b/c') 347 348 You cannot go past an anchor, or empty path:: 349 350 >>> p = PurePosixPath('/') 351 >>> p.parent 352 PurePosixPath('/') 353 >>> p = PurePosixPath('.') 354 >>> p.parent 355 PurePosixPath('.') 356 357 .. note:: 358 This is a purely lexical operation, hence the following behaviour:: 359 360 >>> p = PurePosixPath('foo/..') 361 >>> p.parent 362 PurePosixPath('foo') 363 364 If you want to walk an arbitrary filesystem path upwards, it is 365 recommended to first call :meth:`Path.resolve` so as to resolve 366 symlinks and eliminate `".."` components. 367 368 369.. data:: PurePath.name 370 371 A string representing the final path component, excluding the drive and 372 root, if any:: 373 374 >>> PurePosixPath('my/library/setup.py').name 375 'setup.py' 376 377 UNC drive names are not considered:: 378 379 >>> PureWindowsPath('//some/share/setup.py').name 380 'setup.py' 381 >>> PureWindowsPath('//some/share').name 382 '' 383 384 385.. data:: PurePath.suffix 386 387 The file extension of the final component, if any:: 388 389 >>> PurePosixPath('my/library/setup.py').suffix 390 '.py' 391 >>> PurePosixPath('my/library.tar.gz').suffix 392 '.gz' 393 >>> PurePosixPath('my/library').suffix 394 '' 395 396 397.. data:: PurePath.suffixes 398 399 A list of the path's file extensions:: 400 401 >>> PurePosixPath('my/library.tar.gar').suffixes 402 ['.tar', '.gar'] 403 >>> PurePosixPath('my/library.tar.gz').suffixes 404 ['.tar', '.gz'] 405 >>> PurePosixPath('my/library').suffixes 406 [] 407 408 409.. data:: PurePath.stem 410 411 The final path component, without its suffix:: 412 413 >>> PurePosixPath('my/library.tar.gz').stem 414 'library.tar' 415 >>> PurePosixPath('my/library.tar').stem 416 'library' 417 >>> PurePosixPath('my/library').stem 418 'library' 419 420 421.. method:: PurePath.as_posix() 422 423 Return a string representation of the path with forward slashes (``/``):: 424 425 >>> p = PureWindowsPath('c:\\windows') 426 >>> str(p) 427 'c:\\windows' 428 >>> p.as_posix() 429 'c:/windows' 430 431 432.. method:: PurePath.as_uri() 433 434 Represent the path as a ``file`` URI. :exc:`ValueError` is raised if 435 the path isn't absolute. 436 437 >>> p = PurePosixPath('/etc/passwd') 438 >>> p.as_uri() 439 'file:///etc/passwd' 440 >>> p = PureWindowsPath('c:/Windows') 441 >>> p.as_uri() 442 'file:///c:/Windows' 443 444 445.. method:: PurePath.is_absolute() 446 447 Return whether the path is absolute or not. A path is considered absolute 448 if it has both a root and (if the flavour allows) a drive:: 449 450 >>> PurePosixPath('/a/b').is_absolute() 451 True 452 >>> PurePosixPath('a/b').is_absolute() 453 False 454 455 >>> PureWindowsPath('c:/a/b').is_absolute() 456 True 457 >>> PureWindowsPath('/a/b').is_absolute() 458 False 459 >>> PureWindowsPath('c:').is_absolute() 460 False 461 >>> PureWindowsPath('//some/share').is_absolute() 462 True 463 464 465.. method:: PurePath.is_reserved() 466 467 With :class:`PureWindowsPath`, return ``True`` if the path is considered 468 reserved under Windows, ``False`` otherwise. With :class:`PurePosixPath`, 469 ``False`` is always returned. 470 471 >>> PureWindowsPath('nul').is_reserved() 472 True 473 >>> PurePosixPath('nul').is_reserved() 474 False 475 476 File system calls on reserved paths can fail mysteriously or have 477 unintended effects. 478 479 480.. method:: PurePath.joinpath(*other) 481 482 Calling this method is equivalent to combining the path with each of 483 the *other* arguments in turn:: 484 485 >>> PurePosixPath('/etc').joinpath('passwd') 486 PurePosixPath('/etc/passwd') 487 >>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd')) 488 PurePosixPath('/etc/passwd') 489 >>> PurePosixPath('/etc').joinpath('init.d', 'apache2') 490 PurePosixPath('/etc/init.d/apache2') 491 >>> PureWindowsPath('c:').joinpath('/Program Files') 492 PureWindowsPath('c:/Program Files') 493 494 495.. method:: PurePath.match(pattern) 496 497 Match this path against the provided glob-style pattern. Return ``True`` 498 if matching is successful, ``False`` otherwise. 499 500 If *pattern* is relative, the path can be either relative or absolute, 501 and matching is done from the right:: 502 503 >>> PurePath('a/b.py').match('*.py') 504 True 505 >>> PurePath('/a/b/c.py').match('b/*.py') 506 True 507 >>> PurePath('/a/b/c.py').match('a/*.py') 508 False 509 510 If *pattern* is absolute, the path must be absolute, and the whole path 511 must match:: 512 513 >>> PurePath('/a.py').match('/*.py') 514 True 515 >>> PurePath('a/b.py').match('/*.py') 516 False 517 518 As with other methods, case-sensitivity follows platform defaults:: 519 520 >>> PurePosixPath('b.py').match('*.PY') 521 False 522 >>> PureWindowsPath('b.py').match('*.PY') 523 True 524 525 526.. method:: PurePath.relative_to(*other) 527 528 Compute a version of this path relative to the path represented by 529 *other*. If it's impossible, ValueError is raised:: 530 531 >>> p = PurePosixPath('/etc/passwd') 532 >>> p.relative_to('/') 533 PurePosixPath('etc/passwd') 534 >>> p.relative_to('/etc') 535 PurePosixPath('passwd') 536 >>> p.relative_to('/usr') 537 Traceback (most recent call last): 538 File "<stdin>", line 1, in <module> 539 File "pathlib.py", line 694, in relative_to 540 .format(str(self), str(formatted))) 541 ValueError: '/etc/passwd' does not start with '/usr' 542 543 544.. method:: PurePath.with_name(name) 545 546 Return a new path with the :attr:`name` changed. If the original path 547 doesn't have a name, ValueError is raised:: 548 549 >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz') 550 >>> p.with_name('setup.py') 551 PureWindowsPath('c:/Downloads/setup.py') 552 >>> p = PureWindowsPath('c:/') 553 >>> p.with_name('setup.py') 554 Traceback (most recent call last): 555 File "<stdin>", line 1, in <module> 556 File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name 557 raise ValueError("%r has an empty name" % (self,)) 558 ValueError: PureWindowsPath('c:/') has an empty name 559 560 561.. method:: PurePath.with_suffix(suffix) 562 563 Return a new path with the :attr:`suffix` changed. If the original path 564 doesn't have a suffix, the new *suffix* is appended instead. If the 565 *suffix* is an empty string, the original suffix is removed:: 566 567 >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz') 568 >>> p.with_suffix('.bz2') 569 PureWindowsPath('c:/Downloads/pathlib.tar.bz2') 570 >>> p = PureWindowsPath('README') 571 >>> p.with_suffix('.txt') 572 PureWindowsPath('README.txt') 573 >>> p = PureWindowsPath('README.txt') 574 >>> p.with_suffix('') 575 PureWindowsPath('README') 576 577 578.. _concrete-paths: 579 580 581Concrete paths 582-------------- 583 584Concrete paths are subclasses of the pure path classes. In addition to 585operations provided by the latter, they also provide methods to do system 586calls on path objects. There are three ways to instantiate concrete paths: 587 588.. class:: Path(*pathsegments) 589 590 A subclass of :class:`PurePath`, this class represents concrete paths of 591 the system's path flavour (instantiating it creates either a 592 :class:`PosixPath` or a :class:`WindowsPath`):: 593 594 >>> Path('setup.py') 595 PosixPath('setup.py') 596 597 *pathsegments* is specified similarly to :class:`PurePath`. 598 599.. class:: PosixPath(*pathsegments) 600 601 A subclass of :class:`Path` and :class:`PurePosixPath`, this class 602 represents concrete non-Windows filesystem paths:: 603 604 >>> PosixPath('/etc') 605 PosixPath('/etc') 606 607 *pathsegments* is specified similarly to :class:`PurePath`. 608 609.. class:: WindowsPath(*pathsegments) 610 611 A subclass of :class:`Path` and :class:`PureWindowsPath`, this class 612 represents concrete Windows filesystem paths:: 613 614 >>> WindowsPath('c:/Program Files/') 615 WindowsPath('c:/Program Files') 616 617 *pathsegments* is specified similarly to :class:`PurePath`. 618 619You can only instantiate the class flavour that corresponds to your system 620(allowing system calls on non-compatible path flavours could lead to 621bugs or failures in your application):: 622 623 >>> import os 624 >>> os.name 625 'posix' 626 >>> Path('setup.py') 627 PosixPath('setup.py') 628 >>> PosixPath('setup.py') 629 PosixPath('setup.py') 630 >>> WindowsPath('setup.py') 631 Traceback (most recent call last): 632 File "<stdin>", line 1, in <module> 633 File "pathlib.py", line 798, in __new__ 634 % (cls.__name__,)) 635 NotImplementedError: cannot instantiate 'WindowsPath' on your system 636 637 638Methods 639^^^^^^^ 640 641Concrete paths provide the following methods in addition to pure paths 642methods. Many of these methods can raise an :exc:`OSError` if a system 643call fails (for example because the path doesn't exist). 644 645.. versionchanged:: 3.8 646 647 :meth:`~Path.exists()`, :meth:`~Path.is_dir()`, :meth:`~Path.is_file()`, 648 :meth:`~Path.is_mount()`, :meth:`~Path.is_symlink()`, 649 :meth:`~Path.is_block_device()`, :meth:`~Path.is_char_device()`, 650 :meth:`~Path.is_fifo()`, :meth:`~Path.is_socket()` now return ``False`` 651 instead of raising an exception for paths that contain characters 652 unrepresentable at the OS level. 653 654 655.. classmethod:: Path.cwd() 656 657 Return a new path object representing the current directory (as returned 658 by :func:`os.getcwd`):: 659 660 >>> Path.cwd() 661 PosixPath('/home/antoine/pathlib') 662 663 664.. classmethod:: Path.home() 665 666 Return a new path object representing the user's home directory (as 667 returned by :func:`os.path.expanduser` with ``~`` construct):: 668 669 >>> Path.home() 670 PosixPath('/home/antoine') 671 672 .. versionadded:: 3.5 673 674 675.. method:: Path.stat() 676 677 Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`. 678 The result is looked up at each call to this method. 679 680 :: 681 682 >>> p = Path('setup.py') 683 >>> p.stat().st_size 684 956 685 >>> p.stat().st_mtime 686 1327883547.852554 687 688 689.. method:: Path.chmod(mode) 690 691 Change the file mode and permissions, like :func:`os.chmod`:: 692 693 >>> p = Path('setup.py') 694 >>> p.stat().st_mode 695 33277 696 >>> p.chmod(0o444) 697 >>> p.stat().st_mode 698 33060 699 700 701.. method:: Path.exists() 702 703 Whether the path points to an existing file or directory:: 704 705 >>> Path('.').exists() 706 True 707 >>> Path('setup.py').exists() 708 True 709 >>> Path('/etc').exists() 710 True 711 >>> Path('nonexistentfile').exists() 712 False 713 714 .. note:: 715 If the path points to a symlink, :meth:`exists` returns whether the 716 symlink *points to* an existing file or directory. 717 718 719.. method:: Path.expanduser() 720 721 Return a new path with expanded ``~`` and ``~user`` constructs, 722 as returned by :meth:`os.path.expanduser`:: 723 724 >>> p = PosixPath('~/films/Monty Python') 725 >>> p.expanduser() 726 PosixPath('/home/eric/films/Monty Python') 727 728 .. versionadded:: 3.5 729 730 731.. method:: Path.glob(pattern) 732 733 Glob the given relative *pattern* in the directory represented by this path, 734 yielding all matching files (of any kind):: 735 736 >>> sorted(Path('.').glob('*.py')) 737 [PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')] 738 >>> sorted(Path('.').glob('*/*.py')) 739 [PosixPath('docs/conf.py')] 740 741 The "``**``" pattern means "this directory and all subdirectories, 742 recursively". In other words, it enables recursive globbing:: 743 744 >>> sorted(Path('.').glob('**/*.py')) 745 [PosixPath('build/lib/pathlib.py'), 746 PosixPath('docs/conf.py'), 747 PosixPath('pathlib.py'), 748 PosixPath('setup.py'), 749 PosixPath('test_pathlib.py')] 750 751 .. note:: 752 Using the "``**``" pattern in large directory trees may consume 753 an inordinate amount of time. 754 755 756.. method:: Path.group() 757 758 Return the name of the group owning the file. :exc:`KeyError` is raised 759 if the file's gid isn't found in the system database. 760 761 762.. method:: Path.is_dir() 763 764 Return ``True`` if the path points to a directory (or a symbolic link 765 pointing to a directory), ``False`` if it points to another kind of file. 766 767 ``False`` is also returned if the path doesn't exist or is a broken symlink; 768 other errors (such as permission errors) are propagated. 769 770 771.. method:: Path.is_file() 772 773 Return ``True`` if the path points to a regular file (or a symbolic link 774 pointing to a regular file), ``False`` if it points to another kind of file. 775 776 ``False`` is also returned if the path doesn't exist or is a broken symlink; 777 other errors (such as permission errors) are propagated. 778 779 780.. method:: Path.is_mount() 781 782 Return ``True`` if the path is a :dfn:`mount point`: a point in a 783 file system where a different file system has been mounted. On POSIX, the 784 function checks whether *path*'s parent, :file:`path/..`, is on a different 785 device than *path*, or whether :file:`path/..` and *path* point to the same 786 i-node on the same device --- this should detect mount points for all Unix 787 and POSIX variants. Not implemented on Windows. 788 789 .. versionadded:: 3.7 790 791 792.. method:: Path.is_symlink() 793 794 Return ``True`` if the path points to a symbolic link, ``False`` otherwise. 795 796 ``False`` is also returned if the path doesn't exist; other errors (such 797 as permission errors) are propagated. 798 799 800.. method:: Path.is_socket() 801 802 Return ``True`` if the path points to a Unix socket (or a symbolic link 803 pointing to a Unix socket), ``False`` if it points to another kind of file. 804 805 ``False`` is also returned if the path doesn't exist or is a broken symlink; 806 other errors (such as permission errors) are propagated. 807 808 809.. method:: Path.is_fifo() 810 811 Return ``True`` if the path points to a FIFO (or a symbolic link 812 pointing to a FIFO), ``False`` if it points to another kind of file. 813 814 ``False`` is also returned if the path doesn't exist or is a broken symlink; 815 other errors (such as permission errors) are propagated. 816 817 818.. method:: Path.is_block_device() 819 820 Return ``True`` if the path points to a block device (or a symbolic link 821 pointing to a block device), ``False`` if it points to another kind of file. 822 823 ``False`` is also returned if the path doesn't exist or is a broken symlink; 824 other errors (such as permission errors) are propagated. 825 826 827.. method:: Path.is_char_device() 828 829 Return ``True`` if the path points to a character device (or a symbolic link 830 pointing to a character device), ``False`` if it points to another kind of file. 831 832 ``False`` is also returned if the path doesn't exist or is a broken symlink; 833 other errors (such as permission errors) are propagated. 834 835 836.. method:: Path.iterdir() 837 838 When the path points to a directory, yield path objects of the directory 839 contents:: 840 841 >>> p = Path('docs') 842 >>> for child in p.iterdir(): child 843 ... 844 PosixPath('docs/conf.py') 845 PosixPath('docs/_templates') 846 PosixPath('docs/make.bat') 847 PosixPath('docs/index.rst') 848 PosixPath('docs/_build') 849 PosixPath('docs/_static') 850 PosixPath('docs/Makefile') 851 852 The children are yielded in arbitrary order, and the special entries 853 ``'.'`` and ``'..'`` are not included. If a file is removed from or added 854 to the directory after creating the iterator, whether an path object for 855 that file be included is unspecified. 856 857.. method:: Path.lchmod(mode) 858 859 Like :meth:`Path.chmod` but, if the path points to a symbolic link, the 860 symbolic link's mode is changed rather than its target's. 861 862 863.. method:: Path.lstat() 864 865 Like :meth:`Path.stat` but, if the path points to a symbolic link, return 866 the symbolic link's information rather than its target's. 867 868 869.. method:: Path.mkdir(mode=0o777, parents=False, exist_ok=False) 870 871 Create a new directory at this given path. If *mode* is given, it is 872 combined with the process' ``umask`` value to determine the file mode 873 and access flags. If the path already exists, :exc:`FileExistsError` 874 is raised. 875 876 If *parents* is true, any missing parents of this path are created 877 as needed; they are created with the default permissions without taking 878 *mode* into account (mimicking the POSIX ``mkdir -p`` command). 879 880 If *parents* is false (the default), a missing parent raises 881 :exc:`FileNotFoundError`. 882 883 If *exist_ok* is false (the default), :exc:`FileExistsError` is 884 raised if the target directory already exists. 885 886 If *exist_ok* is true, :exc:`FileExistsError` exceptions will be 887 ignored (same behavior as the POSIX ``mkdir -p`` command), but only if the 888 last path component is not an existing non-directory file. 889 890 .. versionchanged:: 3.5 891 The *exist_ok* parameter was added. 892 893 894.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None) 895 896 Open the file pointed to by the path, like the built-in :func:`open` 897 function does:: 898 899 >>> p = Path('setup.py') 900 >>> with p.open() as f: 901 ... f.readline() 902 ... 903 '#!/usr/bin/env python3\n' 904 905 906.. method:: Path.owner() 907 908 Return the name of the user owning the file. :exc:`KeyError` is raised 909 if the file's uid isn't found in the system database. 910 911 912.. method:: Path.read_bytes() 913 914 Return the binary contents of the pointed-to file as a bytes object:: 915 916 >>> p = Path('my_binary_file') 917 >>> p.write_bytes(b'Binary file contents') 918 20 919 >>> p.read_bytes() 920 b'Binary file contents' 921 922 .. versionadded:: 3.5 923 924 925.. method:: Path.read_text(encoding=None, errors=None) 926 927 Return the decoded contents of the pointed-to file as a string:: 928 929 >>> p = Path('my_text_file') 930 >>> p.write_text('Text file contents') 931 18 932 >>> p.read_text() 933 'Text file contents' 934 935 The file is opened and then closed. The optional parameters have the same 936 meaning as in :func:`open`. 937 938 .. versionadded:: 3.5 939 940 941.. method:: Path.rename(target) 942 943 Rename this file or directory to the given *target*, and return a new Path 944 instance pointing to *target*. On Unix, if *target* exists and is a file, 945 it will be replaced silently if the user has permission. *target* can be 946 either a string or another path object:: 947 948 >>> p = Path('foo') 949 >>> p.open('w').write('some text') 950 9 951 >>> target = Path('bar') 952 >>> p.rename(target) 953 PosixPath('bar') 954 >>> target.open().read() 955 'some text' 956 957 The target path may be absolute or relative. Relative paths are interpreted 958 relative to the current working directory, *not* the directory of the Path 959 object. 960 961 .. versionchanged:: 3.8 962 Added return value, return the new Path instance. 963 964 965.. method:: Path.replace(target) 966 967 Rename this file or directory to the given *target*, and return a new Path 968 instance pointing to *target*. If *target* points to an existing file or 969 directory, it will be unconditionally replaced. 970 971 The target path may be absolute or relative. Relative paths are interpreted 972 relative to the current working directory, *not* the directory of the Path 973 object. 974 975 .. versionchanged:: 3.8 976 Added return value, return the new Path instance. 977 978 979.. method:: Path.resolve(strict=False) 980 981 Make the path absolute, resolving any symlinks. A new path object is 982 returned:: 983 984 >>> p = Path() 985 >>> p 986 PosixPath('.') 987 >>> p.resolve() 988 PosixPath('/home/antoine/pathlib') 989 990 "``..``" components are also eliminated (this is the only method to do so):: 991 992 >>> p = Path('docs/../setup.py') 993 >>> p.resolve() 994 PosixPath('/home/antoine/pathlib/setup.py') 995 996 If the path doesn't exist and *strict* is ``True``, :exc:`FileNotFoundError` 997 is raised. If *strict* is ``False``, the path is resolved as far as possible 998 and any remainder is appended without checking whether it exists. If an 999 infinite loop is encountered along the resolution path, :exc:`RuntimeError` 1000 is raised. 1001 1002 .. versionadded:: 3.6 1003 The *strict* argument (pre-3.6 behavior is strict). 1004 1005.. method:: Path.rglob(pattern) 1006 1007 This is like calling :func:`Path.glob` with "``**/``" added in front of the 1008 given relative *pattern*:: 1009 1010 >>> sorted(Path().rglob("*.py")) 1011 [PosixPath('build/lib/pathlib.py'), 1012 PosixPath('docs/conf.py'), 1013 PosixPath('pathlib.py'), 1014 PosixPath('setup.py'), 1015 PosixPath('test_pathlib.py')] 1016 1017 1018.. method:: Path.rmdir() 1019 1020 Remove this directory. The directory must be empty. 1021 1022 1023.. method:: Path.samefile(other_path) 1024 1025 Return whether this path points to the same file as *other_path*, which 1026 can be either a Path object, or a string. The semantics are similar 1027 to :func:`os.path.samefile` and :func:`os.path.samestat`. 1028 1029 An :exc:`OSError` can be raised if either file cannot be accessed for some 1030 reason. 1031 1032 :: 1033 1034 >>> p = Path('spam') 1035 >>> q = Path('eggs') 1036 >>> p.samefile(q) 1037 False 1038 >>> p.samefile('spam') 1039 True 1040 1041 .. versionadded:: 3.5 1042 1043 1044.. method:: Path.symlink_to(target, target_is_directory=False) 1045 1046 Make this path a symbolic link to *target*. Under Windows, 1047 *target_is_directory* must be true (default ``False``) if the link's target 1048 is a directory. Under POSIX, *target_is_directory*'s value is ignored. 1049 1050 :: 1051 1052 >>> p = Path('mylink') 1053 >>> p.symlink_to('setup.py') 1054 >>> p.resolve() 1055 PosixPath('/home/antoine/pathlib/setup.py') 1056 >>> p.stat().st_size 1057 956 1058 >>> p.lstat().st_size 1059 8 1060 1061 .. note:: 1062 The order of arguments (link, target) is the reverse 1063 of :func:`os.symlink`'s. 1064 1065 1066.. method:: Path.link_to(target) 1067 1068 Make *target* a hard link to this path. 1069 1070 .. warning:: 1071 1072 This function does not make this path a hard link to *target*, despite 1073 the implication of the function and argument names. The argument order 1074 (target, link) is the reverse of :func:`Path.symlink_to`, but matches 1075 that of :func:`os.link`. 1076 1077 .. versionadded:: 3.8 1078 1079 1080.. method:: Path.touch(mode=0o666, exist_ok=True) 1081 1082 Create a file at this given path. If *mode* is given, it is combined 1083 with the process' ``umask`` value to determine the file mode and access 1084 flags. If the file already exists, the function succeeds if *exist_ok* 1085 is true (and its modification time is updated to the current time), 1086 otherwise :exc:`FileExistsError` is raised. 1087 1088 1089.. method:: Path.unlink(missing_ok=False) 1090 1091 Remove this file or symbolic link. If the path points to a directory, 1092 use :func:`Path.rmdir` instead. 1093 1094 If *missing_ok* is false (the default), :exc:`FileNotFoundError` is 1095 raised if the path does not exist. 1096 1097 If *missing_ok* is true, :exc:`FileNotFoundError` exceptions will be 1098 ignored (same behavior as the POSIX ``rm -f`` command). 1099 1100 .. versionchanged:: 3.8 1101 The *missing_ok* parameter was added. 1102 1103 1104.. method:: Path.write_bytes(data) 1105 1106 Open the file pointed to in bytes mode, write *data* to it, and close the 1107 file:: 1108 1109 >>> p = Path('my_binary_file') 1110 >>> p.write_bytes(b'Binary file contents') 1111 20 1112 >>> p.read_bytes() 1113 b'Binary file contents' 1114 1115 An existing file of the same name is overwritten. 1116 1117 .. versionadded:: 3.5 1118 1119 1120.. method:: Path.write_text(data, encoding=None, errors=None) 1121 1122 Open the file pointed to in text mode, write *data* to it, and close the 1123 file:: 1124 1125 >>> p = Path('my_text_file') 1126 >>> p.write_text('Text file contents') 1127 18 1128 >>> p.read_text() 1129 'Text file contents' 1130 1131 An existing file of the same name is overwritten. The optional parameters 1132 have the same meaning as in :func:`open`. 1133 1134 .. versionadded:: 3.5 1135 1136Correspondence to tools in the :mod:`os` module 1137----------------------------------------------- 1138 1139Below is a table mapping various :mod:`os` functions to their corresponding 1140:class:`PurePath`/:class:`Path` equivalent. 1141 1142.. note:: 1143 1144 Although :func:`os.path.relpath` and :meth:`PurePath.relative_to` have some 1145 overlapping use-cases, their semantics differ enough to warrant not 1146 considering them equivalent. 1147 1148==================================== ============================== 1149os and os.path pathlib 1150==================================== ============================== 1151:func:`os.path.abspath` :meth:`Path.resolve` 1152:func:`os.chmod` :meth:`Path.chmod` 1153:func:`os.mkdir` :meth:`Path.mkdir` 1154:func:`os.rename` :meth:`Path.rename` 1155:func:`os.replace` :meth:`Path.replace` 1156:func:`os.rmdir` :meth:`Path.rmdir` 1157:func:`os.remove`, :func:`os.unlink` :meth:`Path.unlink` 1158:func:`os.getcwd` :func:`Path.cwd` 1159:func:`os.path.exists` :meth:`Path.exists` 1160:func:`os.path.expanduser` :meth:`Path.expanduser` and 1161 :meth:`Path.home` 1162:func:`os.listdir` :meth:`Path.iterdir` 1163:func:`os.path.isdir` :meth:`Path.is_dir` 1164:func:`os.path.isfile` :meth:`Path.is_file` 1165:func:`os.path.islink` :meth:`Path.is_symlink` 1166:func:`os.link` :meth:`Path.link_to` 1167:func:`os.symlink` :meth:`Path.symlink_to` 1168:func:`os.stat` :meth:`Path.stat`, 1169 :meth:`Path.owner`, 1170 :meth:`Path.group` 1171:func:`os.path.isabs` :meth:`PurePath.is_absolute` 1172:func:`os.path.join` :func:`PurePath.joinpath` 1173:func:`os.path.basename` :data:`PurePath.name` 1174:func:`os.path.dirname` :data:`PurePath.parent` 1175:func:`os.path.samefile` :meth:`Path.samefile` 1176:func:`os.path.splitext` :data:`PurePath.suffix` 1177==================================== ============================== 1178