@@ -21,6 +21,12 @@ inherit from pure paths but also provide I/O operations.
2121.. image :: pathlib-inheritance.png
2222 :align: center
2323 :class: invert-in-dark-mode
24+ :alt: Inheritance diagram showing the classes available in pathlib. The
25+ most basic class is PurePath, which has three direct subclasses:
26+ PurePosixPath, PureWindowsPath, and Path. Further to these four
27+ classes, there are two classes that use multiple inheritance:
28+ PosixPath subclasses PurePosixPath and Path, and WindowsPath
29+ subclasses PureWindowsPath and Path.
2430
2531If you've never used this module before or just aren't sure which class is
2632right for your task, :class: `Path ` is most likely what you need. It instantiates
@@ -793,6 +799,99 @@ Some concrete path methods can raise an :exc:`OSError` if a system call fails
793799(for example because the path doesn't exist).
794800
795801
802+ Expanding and resolving paths
803+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
804+
805+ .. classmethod :: Path.home()
806+
807+ Return a new path object representing the user's home directory (as
808+ returned by :func: `os.path.expanduser ` with ``~ `` construct). If the home
809+ directory can't be resolved, :exc: `RuntimeError ` is raised.
810+
811+ ::
812+
813+ >>> Path.home()
814+ PosixPath('/home/antoine')
815+
816+ .. versionadded :: 3.5
817+
818+
819+ .. method :: Path.expanduser()
820+
821+ Return a new path with expanded ``~ `` and ``~user `` constructs,
822+ as returned by :meth: `os.path.expanduser `. If a home directory can't be
823+ resolved, :exc: `RuntimeError ` is raised.
824+
825+ ::
826+
827+ >>> p = PosixPath('~/films/Monty Python')
828+ >>> p.expanduser()
829+ PosixPath('/home/eric/films/Monty Python')
830+
831+ .. versionadded :: 3.5
832+
833+
834+ .. classmethod :: Path.cwd()
835+
836+ Return a new path object representing the current directory (as returned
837+ by :func: `os.getcwd `)::
838+
839+ >>> Path.cwd()
840+ PosixPath('/home/antoine/pathlib')
841+
842+
843+ .. method :: Path.absolute()
844+
845+ Make the path absolute, without normalization or resolving symlinks.
846+ Returns a new path object::
847+
848+ >>> p = Path('tests')
849+ >>> p
850+ PosixPath('tests')
851+ >>> p.absolute()
852+ PosixPath('/home/antoine/pathlib/tests')
853+
854+
855+ .. method :: Path.resolve(strict=False)
856+
857+ Make the path absolute, resolving any symlinks. A new path object is
858+ returned::
859+
860+ >>> p = Path()
861+ >>> p
862+ PosixPath('.')
863+ >>> p.resolve()
864+ PosixPath('/home/antoine/pathlib')
865+
866+ "``.. ``" components are also eliminated (this is the only method to do so)::
867+
868+ >>> p = Path('docs/../setup.py')
869+ >>> p.resolve()
870+ PosixPath('/home/antoine/pathlib/setup.py')
871+
872+ If the path doesn't exist and *strict * is ``True ``, :exc: `FileNotFoundError `
873+ is raised. If *strict * is ``False ``, the path is resolved as far as possible
874+ and any remainder is appended without checking whether it exists. If an
875+ infinite loop is encountered along the resolution path, :exc: `RuntimeError `
876+ is raised.
877+
878+ .. versionchanged :: 3.6
879+ The *strict * parameter was added (pre-3.6 behavior is strict).
880+
881+
882+ .. method :: Path.readlink()
883+
884+ Return the path to which the symbolic link points (as returned by
885+ :func: `os.readlink `)::
886+
887+ >>> p = Path('mylink')
888+ >>> p.symlink_to('setup.py')
889+ >>> p.readlink()
890+ PosixPath('setup.py')
891+
892+ .. versionadded :: 3.9
893+
894+
796895Querying file type and status
797896^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
798897
@@ -1380,7 +1479,7 @@ Renaming and deleting
13801479 Remove this directory. The directory must be empty.
13811480
13821481
1383- Ownership and permissions
1482+ Permissions and ownership
13841483^^^^^^^^^^^^^^^^^^^^^^^^^
13851484
13861485.. method :: Path.owner()
@@ -1422,100 +1521,6 @@ Ownership and permissions
14221521 symbolic link's mode is changed rather than its target's.
14231522
14241523
1425- Other methods
1426- ^^^^^^^^^^^^^
1427-
1428- .. classmethod :: Path.cwd()
1429-
1430- Return a new path object representing the current directory (as returned
1431- by :func: `os.getcwd `)::
1432-
1433- >>> Path.cwd()
1434- PosixPath('/home/antoine/pathlib')
1435-
1436-
1437- .. classmethod :: Path.home()
1438-
1439- Return a new path object representing the user's home directory (as
1440- returned by :func: `os.path.expanduser ` with ``~ `` construct). If the home
1441- directory can't be resolved, :exc: `RuntimeError ` is raised.
1442-
1443- ::
1444-
1445- >>> Path.home()
1446- PosixPath('/home/antoine')
1447-
1448- .. versionadded :: 3.5
1449-
1450-
1451- .. method :: Path.expanduser()
1452-
1453- Return a new path with expanded ``~ `` and ``~user `` constructs,
1454- as returned by :meth: `os.path.expanduser `. If a home directory can't be
1455- resolved, :exc: `RuntimeError ` is raised.
1456-
1457- ::
1458-
1459- >>> p = PosixPath('~/films/Monty Python')
1460- >>> p.expanduser()
1461- PosixPath('/home/eric/films/Monty Python')
1462-
1463- .. versionadded :: 3.5
1464-
1465-
1466- .. method :: Path.readlink()
1467-
1468- Return the path to which the symbolic link points (as returned by
1469- :func: `os.readlink `)::
1470-
1471- >>> p = Path('mylink')
1472- >>> p.symlink_to('setup.py')
1473- >>> p.readlink()
1474- PosixPath('setup.py')
1475-
1476- .. versionadded :: 3.9
1477-
1478-
1479- .. method :: Path.absolute()
1480-
1481- Make the path absolute, without normalization or resolving symlinks.
1482- Returns a new path object::
1483-
1484- >>> p = Path('tests')
1485- >>> p
1486- PosixPath('tests')
1487- >>> p.absolute()
1488- PosixPath('/home/antoine/pathlib/tests')
1489-
1490-
1491- .. method :: Path.resolve(strict=False)
1492-
1493- Make the path absolute, resolving any symlinks. A new path object is
1494- returned::
1495-
1496- >>> p = Path()
1497- >>> p
1498- PosixPath('.')
1499- >>> p.resolve()
1500- PosixPath('/home/antoine/pathlib')
1501-
1502- "``.. ``" components are also eliminated (this is the only method to do so)::
1503-
1504- >>> p = Path('docs/../setup.py')
1505- >>> p.resolve()
1506- PosixPath('/home/antoine/pathlib/setup.py')
1507-
1508- If the path doesn't exist and *strict * is ``True ``, :exc: `FileNotFoundError `
1509- is raised. If *strict * is ``False ``, the path is resolved as far as possible
1510- and any remainder is appended without checking whether it exists. If an
1511- infinite loop is encountered along the resolution path, :exc: `RuntimeError `
1512- is raised.
1513-
1514- .. versionchanged :: 3.6
1515- The *strict * parameter was added (pre-3.6 behavior is strict).
1516-
1517-
1518-
15191524Correspondence to tools in the :mod: `os ` module
15201525-----------------------------------------------
15211526
0 commit comments