@@ -2175,7 +2175,7 @@ features:
2175
2175
Accepts a :term: `path-like object `.
2176
2176
2177
2177
2178
- .. function :: lstat(path, *, dir_fd=None)
2178
+ .. function :: lstat(path, *, dir_fd=None, fast=False )
2179
2179
2180
2180
Perform the equivalent of an :c:func: `lstat ` system call on the given path.
2181
2181
Similar to :func: `~os.stat `, but does not follow symbolic links. Return a
@@ -2184,8 +2184,15 @@ features:
2184
2184
On platforms that do not support symbolic links, this is an alias for
2185
2185
:func: `~os.stat `.
2186
2186
2187
+ Passing *fast * as ``True `` may omit some information on some platforms
2188
+ for the sake of performance. These omissions are not guaranteed (that is,
2189
+ the information may be returned anyway), and may change between Python
2190
+ releases without a deprecation period or due to operating system updates
2191
+ without warning. See :class: `stat_result ` documentation for the fields
2192
+ that are guaranteed to be present under this option.
2193
+
2187
2194
As of Python 3.3, this is equivalent to ``os.stat(path, dir_fd=dir_fd,
2188
- follow_symlinks=False) ``.
2195
+ follow_symlinks=False, fast=fast ) ``.
2189
2196
2190
2197
This function can also support :ref: `paths relative to directory descriptors
2191
2198
<dir_fd>`.
@@ -2209,6 +2216,9 @@ features:
2209
2216
Other kinds of reparse points are resolved by the operating system as
2210
2217
for :func: `~os.stat `.
2211
2218
2219
+ .. versionchanged :: 3.12
2220
+ Added the *fast * parameter.
2221
+
2212
2222
2213
2223
.. function :: mkdir(path, mode=0o777, *, dir_fd=None)
2214
2224
@@ -2781,7 +2791,7 @@ features:
2781
2791
for :class: `bytes ` paths on Windows.
2782
2792
2783
2793
2784
- .. function :: stat(path, *, dir_fd=None, follow_symlinks=True)
2794
+ .. function :: stat(path, *, dir_fd=None, follow_symlinks=True, fast=False )
2785
2795
2786
2796
Get the status of a file or a file descriptor. Perform the equivalent of a
2787
2797
:c:func: `stat ` system call on the given path. *path * may be specified as
@@ -2806,6 +2816,13 @@ features:
2806
2816
possible and call :func: `lstat ` on the result. This does not apply to
2807
2817
dangling symlinks or junction points, which will raise the usual exceptions.
2808
2818
2819
+ Passing *fast * as ``True `` may omit some information on some platforms
2820
+ for the sake of performance. These omissions are not guaranteed (that is,
2821
+ the information may be returned anyway), and may change between Python
2822
+ releases without a deprecation period or due to operating system updates
2823
+ without warning. See :class: `stat_result ` documentation for the fields
2824
+ that are guaranteed to be present under this option.
2825
+
2809
2826
.. index :: module: stat
2810
2827
2811
2828
Example::
@@ -2838,19 +2855,32 @@ features:
2838
2855
returns the information for the original path as if
2839
2856
``follow_symlinks=False `` had been specified instead of raising an error.
2840
2857
2858
+ .. versionchanged :: 3.12
2859
+ Added the *fast * parameter.
2860
+
2841
2861
2842
2862
.. class :: stat_result
2843
2863
2844
2864
Object whose attributes correspond roughly to the members of the
2845
2865
:c:type: `stat ` structure. It is used for the result of :func: `os.stat `,
2846
2866
:func: `os.fstat ` and :func: `os.lstat `.
2847
2867
2868
+ When the *fast * argument to these functions is passed ``True ``, some
2869
+ information may be reduced or omitted. Those attributes that are
2870
+ guaranteed to be valid, and those currently known to be omitted, are
2871
+ marked in the documentation below. If not specified and you depend on
2872
+ that field, explicitly pass *fast * as ``False `` to ensure it is
2873
+ calculated.
2874
+
2848
2875
Attributes:
2849
2876
2850
2877
.. attribute :: st_mode
2851
2878
2852
2879
File mode: file type and file mode bits (permissions).
2853
2880
2881
+ When *fast * is ``True ``, only the file type bits are guaranteed
2882
+ to be valid (the mode bits may be zero).
2883
+
2854
2884
.. attribute :: st_ino
2855
2885
2856
2886
Platform dependent, but if non-zero, uniquely identifies the
@@ -2865,6 +2895,8 @@ features:
2865
2895
2866
2896
Identifier of the device on which this file resides.
2867
2897
2898
+ On Windows, when *fast * is ``True ``, this may be zero.
2899
+
2868
2900
.. attribute :: st_nlink
2869
2901
2870
2902
Number of hard links.
@@ -2883,6 +2915,8 @@ features:
2883
2915
The size of a symbolic link is the length of the pathname it contains,
2884
2916
without a terminating null byte.
2885
2917
2918
+ This field is guaranteed to be filled when specifying *fast *.
2919
+
2886
2920
Timestamps:
2887
2921
2888
2922
.. attribute :: st_atime
@@ -2893,6 +2927,8 @@ features:
2893
2927
2894
2928
Time of most recent content modification expressed in seconds.
2895
2929
2930
+ This field is guaranteed to be filled when specifying *fast *.
2931
+
2896
2932
.. attribute :: st_ctime
2897
2933
2898
2934
Platform dependent:
@@ -2909,6 +2945,9 @@ features:
2909
2945
Time of most recent content modification expressed in nanoseconds as an
2910
2946
integer.
2911
2947
2948
+ This field is guaranteed to be filled when specifying *fast *, subject
2949
+ to the note below.
2950
+
2912
2951
.. attribute :: st_ctime_ns
2913
2952
2914
2953
Platform dependent:
@@ -2998,12 +3037,16 @@ features:
2998
3037
:c:func: `GetFileInformationByHandle `. See the ``FILE_ATTRIBUTE_* ``
2999
3038
constants in the :mod: `stat ` module.
3000
3039
3040
+ This field is guaranteed to be filled when specifying *fast *.
3041
+
3001
3042
.. attribute :: st_reparse_tag
3002
3043
3003
3044
When :attr: `st_file_attributes ` has the ``FILE_ATTRIBUTE_REPARSE_POINT ``
3004
3045
set, this field contains the tag identifying the type of reparse point.
3005
3046
See the ``IO_REPARSE_TAG_* `` constants in the :mod: `stat ` module.
3006
3047
3048
+ This field is guaranteed to be filled when specifying *fast *.
3049
+
3007
3050
The standard module :mod: `stat ` defines functions and constants that are
3008
3051
useful for extracting information from a :c:type: `stat ` structure. (On
3009
3052
Windows, some items are filled with dummy values.)
@@ -3039,6 +3082,10 @@ features:
3039
3082
files as :const: `S_IFCHR `, :const: `S_IFIFO ` or :const: `S_IFBLK `
3040
3083
as appropriate.
3041
3084
3085
+ .. versionchanged :: 3.12
3086
+ Added the *fast * argument and defined the minimum set of returned
3087
+ fields.
3088
+
3042
3089
.. function :: statvfs(path)
3043
3090
3044
3091
Perform a :c:func: `statvfs ` system call on the given path. The return value is
0 commit comments