Skip to content

Commit 0db7bb6

Browse files
committed
Changed full= argument to fast=
1 parent 1cddb60 commit 0db7bb6

8 files changed

+69
-64
lines changed

Doc/library/os.rst

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2175,7 +2175,7 @@ features:
21752175
Accepts a :term:`path-like object`.
21762176

21772177

2178-
.. function:: lstat(path, *, dir_fd=None, full=True)
2178+
.. function:: lstat(path, *, dir_fd=None, fast=False)
21792179

21802180
Perform the equivalent of an :c:func:`lstat` system call on the given path.
21812181
Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
@@ -2184,15 +2184,15 @@ features:
21842184
On platforms that do not support symbolic links, this is an alias for
21852185
:func:`~os.stat`.
21862186

2187-
Passing *full* as ``False`` may omit some information on some platforms
2187+
Passing *fast* as ``True`` may omit some information on some platforms
21882188
for the sake of performance. These omissions are not guaranteed (that is,
21892189
the information may be returned anyway), and may change between Python
21902190
releases without a deprecation period or due to operating system updates
21912191
without warning. See :class:`stat_result` documentation for the fields
21922192
that are guaranteed to be present under this option.
21932193

21942194
As of Python 3.3, this is equivalent to ``os.stat(path, dir_fd=dir_fd,
2195-
follow_symlinks=False, full=full)``.
2195+
follow_symlinks=False, fast=fast)``.
21962196

21972197
This function can also support :ref:`paths relative to directory descriptors
21982198
<dir_fd>`.
@@ -2217,7 +2217,7 @@ features:
22172217
for :func:`~os.stat`.
22182218

22192219
.. versionchanged:: 3.12
2220-
Added the *full* parameter.
2220+
Added the *fast* parameter.
22212221

22222222

22232223
.. function:: mkdir(path, mode=0o777, *, dir_fd=None)
@@ -2791,7 +2791,7 @@ features:
27912791
for :class:`bytes` paths on Windows.
27922792

27932793

2794-
.. function:: stat(path, *, dir_fd=None, follow_symlinks=True, full=True)
2794+
.. function:: stat(path, *, dir_fd=None, follow_symlinks=True, fast=False)
27952795

27962796
Get the status of a file or a file descriptor. Perform the equivalent of a
27972797
:c:func:`stat` system call on the given path. *path* may be specified as
@@ -2816,7 +2816,7 @@ features:
28162816
possible and call :func:`lstat` on the result. This does not apply to
28172817
dangling symlinks or junction points, which will raise the usual exceptions.
28182818

2819-
Passing *full* as ``False`` may omit some information on some platforms
2819+
Passing *fast* as ``True`` may omit some information on some platforms
28202820
for the sake of performance. These omissions are not guaranteed (that is,
28212821
the information may be returned anyway), and may change between Python
28222822
releases without a deprecation period or due to operating system updates
@@ -2856,7 +2856,7 @@ features:
28562856
``follow_symlinks=False`` had been specified instead of raising an error.
28572857

28582858
.. versionchanged:: 3.12
2859-
Added the *full* parameter.
2859+
Added the *fast* parameter.
28602860

28612861

28622862
.. class:: stat_result
@@ -2865,19 +2865,20 @@ features:
28652865
:c:type:`stat` structure. It is used for the result of :func:`os.stat`,
28662866
:func:`os.fstat` and :func:`os.lstat`.
28672867

2868-
When the *full* argument to these functions is passed ``False``, some
2868+
When the *fast* argument to these functions is passed ``True``, some
28692869
information may be reduced or omitted. Those attributes that are
28702870
guaranteed to be valid, and those currently known to be omitted, are
28712871
marked in the documentation below. If not specified and you depend on
2872-
that field, pass *full* as ``True`` to ensure it is calculated.
2872+
that field, explicitly pass *fast* as ``False`` to ensure it is
2873+
calculated.
28732874

28742875
Attributes:
28752876

28762877
.. attribute:: st_mode
28772878

28782879
File mode: file type and file mode bits (permissions).
28792880

2880-
When *full* is ``False``, only the file type bits are guaranteed
2881+
When *fast* is ``True``, only the file type bits are guaranteed
28812882
to be valid (the mode bits may be zero).
28822883

28832884
.. attribute:: st_ino
@@ -2894,7 +2895,7 @@ features:
28942895

28952896
Identifier of the device on which this file resides.
28962897

2897-
On Windows, when *full* is ``False``, this may be zero.
2898+
On Windows, when *fast* is ``True``, this may be zero.
28982899

28992900
.. attribute:: st_nlink
29002901

@@ -2914,7 +2915,7 @@ features:
29142915
The size of a symbolic link is the length of the pathname it contains,
29152916
without a terminating null byte.
29162917

2917-
This field is guaranteed to be filled without specifying *full*.
2918+
This field is guaranteed to be filled when specifying *fast*.
29182919

29192920
Timestamps:
29202921

@@ -2926,7 +2927,7 @@ features:
29262927

29272928
Time of most recent content modification expressed in seconds.
29282929

2929-
This field is guaranteed to be filled without specifying *full*.
2930+
This field is guaranteed to be filled when specifying *fast*.
29302931

29312932
.. attribute:: st_ctime
29322933

@@ -2944,7 +2945,7 @@ features:
29442945
Time of most recent content modification expressed in nanoseconds as an
29452946
integer.
29462947

2947-
This field is guaranteed to be filled without specifying *full*, subject
2948+
This field is guaranteed to be filled when specifying *fast*, subject
29482949
to the note below.
29492950

29502951
.. attribute:: st_ctime_ns
@@ -3036,15 +3037,15 @@ features:
30363037
:c:func:`GetFileInformationByHandle`. See the ``FILE_ATTRIBUTE_*``
30373038
constants in the :mod:`stat` module.
30383039

3039-
This field is guaranteed to be filled without specifying *full*.
3040+
This field is guaranteed to be filled when specifying *fast*.
30403041

30413042
.. attribute:: st_reparse_tag
30423043

30433044
When :attr:`st_file_attributes` has the ``FILE_ATTRIBUTE_REPARSE_POINT``
30443045
set, this field contains the tag identifying the type of reparse point.
30453046
See the ``IO_REPARSE_TAG_*`` constants in the :mod:`stat` module.
30463047

3047-
This field is guaranteed to be filled without specifynig *full*.
3048+
This field is guaranteed to be filled when specifying *fast*.
30483049

30493050
The standard module :mod:`stat` defines functions and constants that are
30503051
useful for extracting information from a :c:type:`stat` structure. (On
@@ -3082,7 +3083,8 @@ features:
30823083
as appropriate.
30833084

30843085
.. versionchanged:: 3.12
3085-
Added the *full* argument and defined the minimum
3086+
Added the *fast* argument and defined the minimum set of returned
3087+
fields.
30863088

30873089
.. function:: statvfs(path)
30883090

Include/internal/pycore_global_objects_fini_generated.h

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Include/internal/pycore_global_strings.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -389,6 +389,7 @@ struct _Py_global_strings {
389389
STRUCT_FOR_ID(false)
390390
STRUCT_FOR_ID(family)
391391
STRUCT_FOR_ID(fanout)
392+
STRUCT_FOR_ID(fast)
392393
STRUCT_FOR_ID(fd)
393394
STRUCT_FOR_ID(fd2)
394395
STRUCT_FOR_ID(fdel)
@@ -413,7 +414,6 @@ struct _Py_global_strings {
413414
STRUCT_FOR_ID(fromtimestamp)
414415
STRUCT_FOR_ID(fromutc)
415416
STRUCT_FOR_ID(fset)
416-
STRUCT_FOR_ID(full)
417417
STRUCT_FOR_ID(func)
418418
STRUCT_FOR_ID(future)
419419
STRUCT_FOR_ID(generation)

Include/internal/pycore_runtime_init_generated.h

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Include/internal/pycore_unicodeobject_generated.h

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Lib/test/test_os.py

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -613,14 +613,17 @@ def test_stat_result_pickle(self):
613613
unpickled = pickle.loads(p)
614614
self.assertEqual(result, unpickled)
615615

616-
def test_stat_result_full(self):
616+
def test_stat_result_fast(self):
617617
# Minimum guaranteed fields when requesting incomplete info
618-
result_1 = os.stat(self.fname, full=False)
619-
result_2 = os.stat(self.fname, full=True)
618+
result_1 = os.stat(self.fname, fast=True)
619+
result_2 = os.stat(self.fname, fast=False)
620+
result_3 = os.stat(self.fname)
620621
self.assertEqual(stat.S_IFMT(result_1.st_mode),
621622
stat.S_IFMT(result_2.st_mode))
622623
self.assertEqual(result_1.st_size, result_2.st_size)
623624
self.assertEqual(result_1.st_mtime, result_2.st_mtime)
625+
# Ensure the default matches fast=False
626+
self.assertEqual(result_2, result_3)
624627

625628
@unittest.skipUnless(hasattr(os, 'statvfs'), 'test needs os.statvfs()')
626629
def test_statvfs_attributes(self):

Modules/clinic/posixmodule.c.h

Lines changed: 21 additions & 21 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)