gh-99726: Improves correctness of stat results for Windows, and uses … · python/cpython@0f17576 (original) (raw)

`@@ -2858,6 +2858,12 @@ features:

2858

`` Added support for the :class:~os.PathLike interface. Added support

2859

`` for :class:bytes paths on Windows.

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