Skip to content

Commit 8502064

Browse files
barneygalebarneygale
authored
[3.12] GH-119054: Add "Querying file type and status" section to pathlib docs (GH-119055) (#119952)
Add a dedicated subsection for `Path.stat()`-related methods, specifically `stat()`, `lstat()`, `exists()`, `is_*()`, and `samefile()`. (cherry picked from commit 81d6336)
1 parent c8de0ec commit 8502064

File tree

1 file changed

+151
-145
lines changed

1 file changed

+151
-145
lines changed

‎Doc/library/pathlib.rst

+151-145
Original file line numberDiff line numberDiff line change
@@ -790,12 +790,8 @@ bugs or failures in your application)::
790790
NotImplementedError: cannot instantiate 'WindowsPath' on your system
791791

792792

793-
Methods
794-
^^^^^^^
795-
796-
Concrete paths provide the following methods in addition to pure paths
797-
methods. Many of these methods can raise an :exc:`OSError` if a system
798-
call fails (for example because the path doesn't exist).
793+
Querying file type and status
794+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
799795

800796
.. versionchanged:: 3.8
801797

@@ -807,29 +803,6 @@ call fails (for example because the path doesn't exist).
807803
unrepresentable at the OS level.
808804

809805

810-
.. classmethod:: Path.cwd()
811-
812-
Return a new path object representing the current directory (as returned
813-
by :func:`os.getcwd`)::
814-
815-
>>> Path.cwd()
816-
PosixPath('/home/antoine/pathlib')
817-
818-
819-
.. classmethod:: Path.home()
820-
821-
Return a new path object representing the user's home directory (as
822-
returned by :func:`os.path.expanduser` with ``~`` construct). If the home
823-
directory can't be resolved, :exc:`RuntimeError` is raised.
824-
825-
::
826-
827-
>>> Path.home()
828-
PosixPath('/home/antoine')
829-
830-
.. versionadded:: 3.5
831-
832-
833806
.. method:: Path.stat(*, follow_symlinks=True)
834807

835808
Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`.
@@ -849,25 +822,12 @@ call fails (for example because the path doesn't exist).
849822
.. versionchanged:: 3.10
850823
The *follow_symlinks* parameter was added.
851824

852-
.. method:: Path.chmod(mode, *, follow_symlinks=True)
853-
854-
Change the file mode and permissions, like :func:`os.chmod`.
855-
856-
This method normally follows symlinks. Some Unix flavours support changing
857-
permissions on the symlink itself; on these platforms you may add the
858-
argument ``follow_symlinks=False``, or use :meth:`~Path.lchmod`.
859825

860-
::
826+
.. method:: Path.lstat()
861827

862-
>>> p = Path('setup.py')
863-
>>> p.stat().st_mode
864-
33277
865-
>>> p.chmod(0o444)
866-
>>> p.stat().st_mode
867-
33060
828+
Like :meth:`Path.stat` but, if the path points to a symbolic link, return
829+
the symbolic link's information rather than its target's.
868830

869-
.. versionchanged:: 3.10
870-
The *follow_symlinks* parameter was added.
871831

872832
.. method:: Path.exists(*, follow_symlinks=True)
873833

@@ -890,69 +850,14 @@ call fails (for example because the path doesn't exist).
890850
.. versionchanged:: 3.12
891851
The *follow_symlinks* parameter was added.
892852

893-
.. method:: Path.expanduser()
894-
895-
Return a new path with expanded ``~`` and ``~user`` constructs,
896-
as returned by :meth:`os.path.expanduser`. If a home directory can't be
897-
resolved, :exc:`RuntimeError` is raised.
898-
899-
::
900-
901-
>>> p = PosixPath('~/films/Monty Python')
902-
>>> p.expanduser()
903-
PosixPath('/home/eric/films/Monty Python')
904-
905-
.. versionadded:: 3.5
906-
907-
908-
.. method:: Path.glob(pattern, *, case_sensitive=None)
909-
910-
Glob the given relative *pattern* in the directory represented by this path,
911-
yielding all matching files (of any kind)::
912-
913-
>>> sorted(Path('.').glob('*.py'))
914-
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
915-
>>> sorted(Path('.').glob('*/*.py'))
916-
[PosixPath('docs/conf.py')]
917-
918-
Patterns are the same as for :mod:`fnmatch`, with the addition of "``**``"
919-
which means "this directory and all subdirectories, recursively". In other
920-
words, it enables recursive globbing::
921-
922-
>>> sorted(Path('.').glob('**/*.py'))
923-
[PosixPath('build/lib/pathlib.py'),
924-
PosixPath('docs/conf.py'),
925-
PosixPath('pathlib.py'),
926-
PosixPath('setup.py'),
927-
PosixPath('test_pathlib.py')]
928-
929-
This method calls :meth:`Path.is_dir` on the top-level directory and
930-
propagates any :exc:`OSError` exception that is raised. Subsequent
931-
:exc:`OSError` exceptions from scanning directories are suppressed.
932-
933-
By default, or when the *case_sensitive* keyword-only argument is set to
934-
``None``, this method matches paths using platform-specific casing rules:
935-
typically, case-sensitive on POSIX, and case-insensitive on Windows.
936-
Set *case_sensitive* to ``True`` or ``False`` to override this behaviour.
937-
938-
.. note::
939-
Using the "``**``" pattern in large directory trees may consume
940-
an inordinate amount of time.
941-
942-
.. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
943-
944-
.. versionchanged:: 3.11
945-
Return only directories if *pattern* ends with a pathname components
946-
separator (:data:`~os.sep` or :data:`~os.altsep`).
947-
948-
.. versionchanged:: 3.12
949-
The *case_sensitive* parameter was added.
950853

854+
.. method:: Path.is_file()
951855

952-
.. method:: Path.group()
856+
Return ``True`` if the path points to a regular file (or a symbolic link
857+
pointing to a regular file), ``False`` if it points to another kind of file.
953858

954-
Return the name of the group owning the file. :exc:`KeyError` is raised
955-
if the file's gid isn't found in the system database.
859+
``False`` is also returned if the path doesn't exist or is a broken symlink;
860+
other errors (such as permission errors) are propagated.
956861

957862

958863
.. method:: Path.is_dir()
@@ -964,13 +869,12 @@ call fails (for example because the path doesn't exist).
964869
other errors (such as permission errors) are propagated.
965870

966871

967-
.. method:: Path.is_file()
872+
.. method:: Path.is_symlink()
968873

969-
Return ``True`` if the path points to a regular file (or a symbolic link
970-
pointing to a regular file), ``False`` if it points to another kind of file.
874+
Return ``True`` if the path points to a symbolic link, ``False`` otherwise.
971875

972-
``False`` is also returned if the path doesn't exist or is a broken symlink;
973-
other errors (such as permission errors) are propagated.
876+
``False`` is also returned if the path doesn't exist; other errors (such
877+
as permission errors) are propagated.
974878

975879

976880
.. method:: Path.is_junction()
@@ -998,14 +902,6 @@ call fails (for example because the path doesn't exist).
998902
Windows support was added.
999903

1000904

1001-
.. method:: Path.is_symlink()
1002-
1003-
Return ``True`` if the path points to a symbolic link, ``False`` otherwise.
1004-
1005-
``False`` is also returned if the path doesn't exist; other errors (such
1006-
as permission errors) are propagated.
1007-
1008-
1009905
.. method:: Path.is_socket()
1010906

1011907
Return ``True`` if the path points to a Unix socket (or a symbolic link
@@ -1042,6 +938,143 @@ call fails (for example because the path doesn't exist).
1042938
other errors (such as permission errors) are propagated.
1043939

1044940

941+
.. method:: Path.samefile(other_path)
942+
943+
Return whether this path points to the same file as *other_path*, which
944+
can be either a Path object, or a string. The semantics are similar
945+
to :func:`os.path.samefile` and :func:`os.path.samestat`.
946+
947+
An :exc:`OSError` can be raised if either file cannot be accessed for some
948+
reason.
949+
950+
::
951+
952+
>>> p = Path('spam')
953+
>>> q = Path('eggs')
954+
>>> p.samefile(q)
955+
False
956+
>>> p.samefile('spam')
957+
True
958+
959+
.. versionadded:: 3.5
960+
961+
962+
Other methods
963+
^^^^^^^^^^^^^
964+
965+
Many of these methods can raise an :exc:`OSError` if a system call fails (for
966+
example because the path doesn't exist).
967+
968+
969+
.. classmethod:: Path.cwd()
970+
971+
Return a new path object representing the current directory (as returned
972+
by :func:`os.getcwd`)::
973+
974+
>>> Path.cwd()
975+
PosixPath('/home/antoine/pathlib')
976+
977+
978+
.. classmethod:: Path.home()
979+
980+
Return a new path object representing the user's home directory (as
981+
returned by :func:`os.path.expanduser` with ``~`` construct). If the home
982+
directory can't be resolved, :exc:`RuntimeError` is raised.
983+
984+
::
985+
986+
>>> Path.home()
987+
PosixPath('/home/antoine')
988+
989+
.. versionadded:: 3.5
990+
991+
992+
.. method:: Path.chmod(mode, *, follow_symlinks=True)
993+
994+
Change the file mode and permissions, like :func:`os.chmod`.
995+
996+
This method normally follows symlinks. Some Unix flavours support changing
997+
permissions on the symlink itself; on these platforms you may add the
998+
argument ``follow_symlinks=False``, or use :meth:`~Path.lchmod`.
999+
1000+
::
1001+
1002+
>>> p = Path('setup.py')
1003+
>>> p.stat().st_mode
1004+
33277
1005+
>>> p.chmod(0o444)
1006+
>>> p.stat().st_mode
1007+
33060
1008+
1009+
.. versionchanged:: 3.10
1010+
The *follow_symlinks* parameter was added.
1011+
1012+
1013+
.. method:: Path.expanduser()
1014+
1015+
Return a new path with expanded ``~`` and ``~user`` constructs,
1016+
as returned by :meth:`os.path.expanduser`. If a home directory can't be
1017+
resolved, :exc:`RuntimeError` is raised.
1018+
1019+
::
1020+
1021+
>>> p = PosixPath('~/films/Monty Python')
1022+
>>> p.expanduser()
1023+
PosixPath('/home/eric/films/Monty Python')
1024+
1025+
.. versionadded:: 3.5
1026+
1027+
1028+
.. method:: Path.glob(pattern, *, case_sensitive=None)
1029+
1030+
Glob the given relative *pattern* in the directory represented by this path,
1031+
yielding all matching files (of any kind)::
1032+
1033+
>>> sorted(Path('.').glob('*.py'))
1034+
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
1035+
>>> sorted(Path('.').glob('*/*.py'))
1036+
[PosixPath('docs/conf.py')]
1037+
1038+
Patterns are the same as for :mod:`fnmatch`, with the addition of "``**``"
1039+
which means "this directory and all subdirectories, recursively". In other
1040+
words, it enables recursive globbing::
1041+
1042+
>>> sorted(Path('.').glob('**/*.py'))
1043+
[PosixPath('build/lib/pathlib.py'),
1044+
PosixPath('docs/conf.py'),
1045+
PosixPath('pathlib.py'),
1046+
PosixPath('setup.py'),
1047+
PosixPath('test_pathlib.py')]
1048+
1049+
This method calls :meth:`Path.is_dir` on the top-level directory and
1050+
propagates any :exc:`OSError` exception that is raised. Subsequent
1051+
:exc:`OSError` exceptions from scanning directories are suppressed.
1052+
1053+
By default, or when the *case_sensitive* keyword-only argument is set to
1054+
``None``, this method matches paths using platform-specific casing rules:
1055+
typically, case-sensitive on POSIX, and case-insensitive on Windows.
1056+
Set *case_sensitive* to ``True`` or ``False`` to override this behaviour.
1057+
1058+
.. note::
1059+
Using the "``**``" pattern in large directory trees may consume
1060+
an inordinate amount of time.
1061+
1062+
.. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
1063+
1064+
.. versionchanged:: 3.11
1065+
Return only directories if *pattern* ends with a pathname components
1066+
separator (:data:`~os.sep` or :data:`~os.altsep`).
1067+
1068+
.. versionchanged:: 3.12
1069+
The *case_sensitive* parameter was added.
1070+
1071+
1072+
.. method:: Path.group()
1073+
1074+
Return the name of the group owning the file. :exc:`KeyError` is raised
1075+
if the file's gid isn't found in the system database.
1076+
1077+
10451078
.. method:: Path.iterdir()
10461079

10471080
When the path points to a directory, yield path objects of the directory
@@ -1164,12 +1197,6 @@ call fails (for example because the path doesn't exist).
11641197
symbolic link's mode is changed rather than its target's.
11651198

11661199

1167-
.. method:: Path.lstat()
1168-
1169-
Like :meth:`Path.stat` but, if the path points to a symbolic link, return
1170-
the symbolic link's information rather than its target's.
1171-
1172-
11731200
.. method:: Path.mkdir(mode=0o777, parents=False, exist_ok=False)
11741201

11751202
Create a new directory at this given path. If *mode* is given, it is
@@ -1367,27 +1394,6 @@ call fails (for example because the path doesn't exist).
13671394
Remove this directory. The directory must be empty.
13681395

13691396

1370-
.. method:: Path.samefile(other_path)
1371-
1372-
Return whether this path points to the same file as *other_path*, which
1373-
can be either a Path object, or a string. The semantics are similar
1374-
to :func:`os.path.samefile` and :func:`os.path.samestat`.
1375-
1376-
An :exc:`OSError` can be raised if either file cannot be accessed for some
1377-
reason.
1378-
1379-
::
1380-
1381-
>>> p = Path('spam')
1382-
>>> q = Path('eggs')
1383-
>>> p.samefile(q)
1384-
False
1385-
>>> p.samefile('spam')
1386-
True
1387-
1388-
.. versionadded:: 3.5
1389-
1390-
13911397
.. method:: Path.symlink_to(target, target_is_directory=False)
13921398

13931399
Make this path a symbolic link pointing to *target*.

0 commit comments

Comments
 (0)