@@ -873,7 +873,7 @@ Methods
873
873
^^^^^^^
874
874
875
875
Concrete paths provide the following methods in addition to pure paths
876
- methods. Many of these methods can raise an :exc: `OSError ` if a system
876
+ methods. Some of these methods can raise an :exc: `OSError ` if a system
877
877
call fails (for example because the path doesn't exist).
878
878
879
879
.. versionchanged :: 3.8
@@ -885,6 +885,15 @@ call fails (for example because the path doesn't exist).
885
885
instead of raising an exception for paths that contain characters
886
886
unrepresentable at the OS level.
887
887
888
+ .. versionchanged :: 3.14
889
+
890
+ The methods given above now return ``False `` instead of raising any
891
+ :exc: `OSError ` exception from the operating system. In previous versions,
892
+ some kinds of :exc: `OSError ` exception are raised, and others suppressed.
893
+ The new behaviour is consistent with :func: `os.path.exists `,
894
+ :func: `os.path.isdir `, etc. Use :meth: `~Path.stat ` to retrieve the file
895
+ status without suppressing exceptions.
896
+
888
897
889
898
.. classmethod :: Path.cwd()
890
899
@@ -951,6 +960,8 @@ call fails (for example because the path doesn't exist).
951
960
.. method :: Path.exists(*, follow_symlinks=True)
952
961
953
962
Return ``True `` if the path points to an existing file or directory.
963
+ ``False `` will be returned if the path is invalid, inaccessible or missing.
964
+ Use :meth: `Path.stat ` to distinguish between these cases.
954
965
955
966
This method normally follows symlinks; to check if a symlink exists, add
956
967
the argument ``follow_symlinks=False ``.
@@ -1067,11 +1078,10 @@ call fails (for example because the path doesn't exist).
1067
1078
1068
1079
.. method :: Path.is_dir(*, follow_symlinks=True)
1069
1080
1070
- Return ``True `` if the path points to a directory, ``False `` if it points
1071
- to another kind of file.
1072
-
1073
- ``False `` is also returned if the path doesn't exist or is a broken symlink;
1074
- other errors (such as permission errors) are propagated.
1081
+ Return ``True `` if the path points to a directory. ``False `` will be
1082
+ returned if the path is invalid, inaccessible or missing, or if it points
1083
+ to something other than a directory. Use :meth: `Path.stat ` to distinguish
1084
+ between these cases.
1075
1085
1076
1086
This method normally follows symlinks; to exclude symlinks to directories,
1077
1087
add the argument ``follow_symlinks=False ``.
@@ -1082,11 +1092,10 @@ call fails (for example because the path doesn't exist).
1082
1092
1083
1093
.. method :: Path.is_file(*, follow_symlinks=True)
1084
1094
1085
- Return ``True `` if the path points to a regular file, ``False `` if it
1086
- points to another kind of file.
1087
-
1088
- ``False `` is also returned if the path doesn't exist or is a broken symlink;
1089
- other errors (such as permission errors) are propagated.
1095
+ Return ``True `` if the path points to a regular file. ``False `` will be
1096
+ returned if the path is invalid, inaccessible or missing, or if it points
1097
+ to something other than a regular file. Use :meth: `Path.stat ` to
1098
+ distinguish between these cases.
1090
1099
1091
1100
This method normally follows symlinks; to exclude symlinks, add the
1092
1101
argument ``follow_symlinks=False ``.
@@ -1122,46 +1131,42 @@ call fails (for example because the path doesn't exist).
1122
1131
1123
1132
.. method :: Path.is_symlink()
1124
1133
1125
- Return ``True `` if the path points to a symbolic link, `` False `` otherwise.
1126
-
1127
- `` False `` is also returned if the path doesn't exist; other errors (such
1128
- as permission errors) are propagated .
1134
+ Return ``True `` if the path points to a symbolic link, even if that symlink
1135
+ is broken. `` False `` will be returned if the path is invalid, inaccessible
1136
+ or missing, or if it points to something other than a symbolic link. Use
1137
+ :meth: ` Path.stat ` to distinguish between these cases .
1129
1138
1130
1139
1131
1140
.. method :: Path.is_socket()
1132
1141
1133
- Return ``True `` if the path points to a Unix socket (or a symbolic link
1134
- pointing to a Unix socket), ``False `` if it points to another kind of file.
1135
-
1136
- ``False `` is also returned if the path doesn't exist or is a broken symlink;
1137
- other errors (such as permission errors) are propagated.
1142
+ Return ``True `` if the path points to a Unix socket. ``False `` will be
1143
+ returned if the path is invalid, inaccessible or missing, or if it points
1144
+ to something other than a Unix socket. Use :meth: `Path.stat ` to
1145
+ distinguish between these cases.
1138
1146
1139
1147
1140
1148
.. method :: Path.is_fifo()
1141
1149
1142
- Return ``True `` if the path points to a FIFO (or a symbolic link
1143
- pointing to a FIFO), ``False `` if it points to another kind of file.
1144
-
1145
- ``False `` is also returned if the path doesn't exist or is a broken symlink;
1146
- other errors (such as permission errors) are propagated.
1150
+ Return ``True `` if the path points to a FIFO. ``False `` will be returned if
1151
+ the path is invalid, inaccessible or missing, or if it points to something
1152
+ other than a FIFO. Use :meth: `Path.stat ` to distinguish between these
1153
+ cases.
1147
1154
1148
1155
1149
1156
.. method :: Path.is_block_device()
1150
1157
1151
- Return ``True `` if the path points to a block device (or a symbolic link
1152
- pointing to a block device), ``False `` if it points to another kind of file.
1153
-
1154
- ``False `` is also returned if the path doesn't exist or is a broken symlink;
1155
- other errors (such as permission errors) are propagated.
1158
+ Return ``True `` if the path points to a block device. ``False `` will be
1159
+ returned if the path is invalid, inaccessible or missing, or if it points
1160
+ to something other than a block device. Use :meth: `Path.stat ` to
1161
+ distinguish between these cases.
1156
1162
1157
1163
1158
1164
.. method :: Path.is_char_device()
1159
1165
1160
- Return ``True `` if the path points to a character device (or a symbolic link
1161
- pointing to a character device), ``False `` if it points to another kind of file.
1162
-
1163
- ``False `` is also returned if the path doesn't exist or is a broken symlink;
1164
- other errors (such as permission errors) are propagated.
1166
+ Return ``True `` if the path points to a character device. ``False `` will be
1167
+ returned if the path is invalid, inaccessible or missing, or if it points
1168
+ to something other than a character device. Use :meth: `Path.stat ` to
1169
+ distinguish between these cases.
1165
1170
1166
1171
1167
1172
.. method :: Path.iterdir()
0 commit comments