@@ -2858,6 +2858,12 @@ features:
2858
2858
Added support for the :class: `~os.PathLike ` interface. Added support
2859
2859
for :class: `bytes ` paths on Windows.
2860
2860
2861
+ .. versionchanged :: 3.12
2862
+ The ``st_ctime `` attribute of a stat result is deprecated on Windows.
2863
+ The file creation time is properly available as ``st_birthtime ``, and
2864
+ in the future ``st_ctime `` may be changed to return zero or the
2865
+ metadata change time, if available.
2866
+
2861
2867
2862
2868
.. function :: stat(path, *, dir_fd=None, follow_symlinks=True)
2863
2869
@@ -2973,10 +2979,12 @@ features:
2973
2979
2974
2980
.. attribute :: st_ctime
2975
2981
2976
- Platform dependent:
2982
+ Time of most recent metadata change expressed in seconds.
2977
2983
2978
- * the time of most recent metadata change on Unix,
2979
- * the time of creation on Windows, expressed in seconds.
2984
+ .. versionchanged :: 3.12
2985
+ ``st_ctime `` is deprecated on Windows. Use ``st_birthtime `` for
2986
+ the file creation time. In the future, ``st_ctime `` will contain
2987
+ the time of the most recent metadata change, as for other platforms.
2980
2988
2981
2989
.. attribute :: st_atime_ns
2982
2990
@@ -2989,29 +2997,48 @@ features:
2989
2997
2990
2998
.. attribute :: st_ctime_ns
2991
2999
2992
- Platform dependent:
3000
+ Time of most recent metadata change expressed in nanoseconds as an
3001
+ integer.
3002
+
3003
+ .. versionchanged :: 3.12
3004
+ ``st_ctime_ns `` is deprecated on Windows. Use ``st_birthtime_ns ``
3005
+ for the file creation time. In the future, ``st_ctime `` will contain
3006
+ the time of the most recent metadata change, as for other platforms.
3007
+
3008
+ .. attribute :: st_birthtime
3009
+
3010
+ Time of file creation expressed in seconds. This attribute is not
3011
+ always available, and may raise :exc: `AttributeError `.
3012
+
3013
+ .. versionchanged :: 3.12
3014
+ ``st_birthtime `` is now available on Windows.
3015
+
3016
+ .. attribute :: st_birthtime_ns
2993
3017
2994
- * the time of most recent metadata change on Unix,
2995
- * the time of creation on Windows, expressed in nanoseconds as an
2996
- integer.
3018
+ Time of file creation expressed in nanoseconds as an integer.
3019
+ This attribute is not always available, and may raise
3020
+ :exc: `AttributeError `.
3021
+
3022
+ .. versionadded :: 3.12
2997
3023
2998
3024
.. note ::
2999
3025
3000
3026
The exact meaning and resolution of the :attr: `st_atime `,
3001
- :attr: `st_mtime `, and :attr: `st_ctime ` attributes depend on the operating
3002
- system and the file system. For example, on Windows systems using the FAT
3003
- or FAT32 file systems, :attr: `st_mtime ` has 2-second resolution, and
3004
- :attr: `st_atime ` has only 1-day resolution. See your operating system
3005
- documentation for details.
3027
+ :attr: `st_mtime `, :attr: `st_ctime ` and :attr: ` st_birthtime ` attributes
3028
+ depend on the operating system and the file system. For example, on
3029
+ Windows systems using the FAT32 file systems, :attr: `st_mtime ` has
3030
+ 2-second resolution, and :attr: `st_atime ` has only 1-day resolution.
3031
+ See your operating system documentation for details.
3006
3032
3007
3033
Similarly, although :attr: `st_atime_ns `, :attr: `st_mtime_ns `,
3008
- and :attr: `st_ctime_ns ` are always expressed in nanoseconds, many
3009
- systems do not provide nanosecond precision. On systems that do
3010
- provide nanosecond precision, the floating-point object used to
3011
- store :attr: `st_atime `, :attr: `st_mtime `, and :attr: `st_ctime `
3012
- cannot preserve all of it, and as such will be slightly inexact.
3013
- If you need the exact timestamps you should always use
3014
- :attr: `st_atime_ns `, :attr: `st_mtime_ns `, and :attr: `st_ctime_ns `.
3034
+ :attr: `st_ctime_ns ` and :attr: `st_birthtime_ns ` are always expressed in
3035
+ nanoseconds, many systems do not provide nanosecond precision. On
3036
+ systems that do provide nanosecond precision, the floating-point object
3037
+ used to store :attr: `st_atime `, :attr: `st_mtime `, :attr: `st_ctime ` and
3038
+ :attr: `st_birthtime ` cannot preserve all of it, and as such will be
3039
+ slightly inexact. If you need the exact timestamps you should always use
3040
+ :attr: `st_atime_ns `, :attr: `st_mtime_ns `, :attr: `st_ctime_ns ` and
3041
+ :attr: `st_birthtime_ns `.
3015
3042
3016
3043
On some Unix systems (such as Linux), the following attributes may also be
3017
3044
available:
@@ -3041,10 +3068,6 @@ features:
3041
3068
3042
3069
File generation number.
3043
3070
3044
- .. attribute :: st_birthtime
3045
-
3046
- Time of file creation.
3047
-
3048
3071
On Solaris and derivatives, the following attributes may also be
3049
3072
available:
3050
3073
@@ -3117,6 +3140,25 @@ features:
3117
3140
files as :const: `S_IFCHR `, :const: `S_IFIFO ` or :const: `S_IFBLK `
3118
3141
as appropriate.
3119
3142
3143
+ .. versionchanged :: 3.12
3144
+ On Windows, :attr: `st_ctime ` is deprecated. Eventually, it will
3145
+ contain the last metadata change time, for consistency with other
3146
+ platforms, but for now still contains creation time.
3147
+ Use :attr: `st_birthtime ` for the creation time.
3148
+
3149
+ .. versionchanged :: 3.12
3150
+ On Windows, :attr: `st_ino ` may now be up to 128 bits, depending
3151
+ on the file system. Previously it would not be above 64 bits, and
3152
+ larger file identifiers would be arbitrarily packed.
3153
+
3154
+ .. versionchanged :: 3.12
3155
+ On Windows, :attr: `st_rdev ` no longer returns a value. Previously
3156
+ it would contain the same as :attr: `st_dev `, which was incorrect.
3157
+
3158
+ .. versionadded :: 3.12
3159
+ Added the :attr: `st_birthtime ` member on Windows.
3160
+
3161
+
3120
3162
.. function :: statvfs(path)
3121
3163
3122
3164
Perform a :c:func: `statvfs ` system call on the given path. The return value is
0 commit comments