Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e1d24f7

Browse files
vstinnervstinner
committed
Issue #21813: Enhance documentation of the os.stat_result class.
2 parents 24ad98b + 992019c commit e1d24f7

2 files changed

Lines changed: 191 additions & 81 deletions

File tree

‎Doc/library/os.rst‎

Lines changed: 189 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -765,8 +765,14 @@ as internal buffering of data.
765765

766766
.. function:: fstat(fd)
767767

768-
Return status for file descriptor *fd*, like :func:`~os.stat`. As of Python
769-
3.3, this is equivalent to ``os.stat(fd)``.
768+
Get the status of the file descriptor *fd*. Return a :class:`stat_result`
769+
object.
770+
771+
As of Python 3.3, this is equivalent to ``os.stat(fd)``.
772+
773+
.. seealso::
774+
775+
The :func:`stat` function.
770776

771777
Availability: Unix, Windows.
772778

@@ -1578,17 +1584,25 @@ features:
15781584
Added support for specifying an open file descriptor for *path*.
15791585

15801586

1581-
.. function:: lstat(path, *, dir_fd=None)
1587+
.. function:: lstat(path, \*, dir_fd=None)
15821588

15831589
Perform the equivalent of an :c:func:`lstat` system call on the given path.
1584-
Similar to :func:`~os.stat`, but does not follow symbolic links. On
1585-
platforms that do not support symbolic links, this is an alias for
1586-
:func:`~os.stat`. As of Python 3.3, this is equivalent to ``os.stat(path,
1587-
dir_fd=dir_fd, follow_symlinks=False)``.
1590+
Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
1591+
:class:`stat_result` object.
1592+
1593+
On platforms that do not support symbolic links, this is an alias for
1594+
:func:`~os.stat`.
1595+
1596+
As of Python 3.3, this is equivalent to ``os.stat(path, dir_fd=dir_fd,
1597+
follow_symlinks=False)``.
15881598

15891599
This function can also support :ref:`paths relative to directory descriptors
15901600
<dir_fd>`.
15911601

1602+
.. seealso::
1603+
1604+
The :func:`stat` function.
1605+
15921606
.. versionchanged:: 3.2
15931607
Added support for Windows 6.0 (Vista) symbolic links.
15941608

@@ -1855,54 +1869,116 @@ features:
18551869
The *dir_fd* parameter.
18561870

18571871

1858-
.. function:: stat(path, *, dir_fd=None, follow_symlinks=True)
1859-
1860-
Perform the equivalent of a :c:func:`stat` system call on the given path.
1861-
*path* may be specified as either a string or as an open file descriptor.
1862-
(This function normally follows symlinks; to stat a symlink add the argument
1863-
``follow_symlinks=False``, or use :func:`lstat`.)
1864-
1865-
The return value is an object whose attributes correspond roughly
1866-
to the members of the :c:type:`stat` structure, namely:
1867-
1868-
* :attr:`st_mode` - protection bits,
1869-
* :attr:`st_ino` - inode number,
1870-
* :attr:`st_dev` - device,
1871-
* :attr:`st_nlink` - number of hard links,
1872-
* :attr:`st_uid` - user id of owner,
1873-
* :attr:`st_gid` - group id of owner,
1874-
* :attr:`st_size` - size of file, in bytes,
1875-
* :attr:`st_atime` - time of most recent access expressed in seconds,
1876-
* :attr:`st_mtime` - time of most recent content modification
1877-
expressed in seconds,
1878-
* :attr:`st_ctime` - platform dependent; time of most recent metadata
1879-
change on Unix, or the time of creation on Windows, expressed in seconds
1880-
* :attr:`st_atime_ns` - time of most recent access
1881-
expressed in nanoseconds as an integer,
1882-
* :attr:`st_mtime_ns` - time of most recent content modification
1883-
expressed in nanoseconds as an integer,
1884-
* :attr:`st_ctime_ns` - platform dependent; time of most recent metadata
1885-
change on Unix, or the time of creation on Windows,
1886-
expressed in nanoseconds as an integer
1872+
.. function:: stat(path, \*, dir_fd=None, follow_symlinks=True)
18871873

1888-
On some Unix systems (such as Linux), the following attributes may also be
1889-
available:
1874+
Get the status of a file or a file descriptor. Perform the equivalent of a
1875+
:c:func:`stat` system call on the given path. *path* may be specified as
1876+
either a string or as an open file descriptor. Return a :class:`stat_result`
1877+
object.
18901878

1891-
* :attr:`st_blocks` - number of 512-byte blocks allocated for file
1892-
* :attr:`st_blksize` - filesystem blocksize for efficient file system I/O
1893-
* :attr:`st_rdev` - type of device if an inode device
1894-
* :attr:`st_flags` - user defined flags for file
1879+
This function normally follows symlinks; to stat a symlink add the argument
1880+
``follow_symlinks=False``, or use :func:`lstat`.
18951881

1896-
On other Unix systems (such as FreeBSD), the following attributes may be
1897-
available (but may be only filled out if root tries to use them):
1882+
This function can support :ref:`specifying a file descriptor <path_fd>` and
1883+
:ref:`not following symlinks <follow_symlinks>`.
18981884

1899-
* :attr:`st_gen` - file generation number
1900-
* :attr:`st_birthtime` - time of file creation
1885+
.. index:: module: stat
19011886

1902-
On Windows systems, the following attribute is also available:
1887+
Example::
1888+
1889+
>>> import os
1890+
>>> statinfo = os.stat('somefile.txt')
1891+
>>> statinfo
1892+
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
1893+
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
1894+
st_mtime=1297230027, st_ctime=1297230027)
1895+
>>> statinfo.st_size
1896+
264
1897+
1898+
Availability: Unix, Windows.
1899+
1900+
.. seealso::
1901+
1902+
:func:`fstat` and :func:`lstat` functions.
1903+
1904+
.. versionadded:: 3.3
1905+
Added the *dir_fd* and *follow_symlinks* arguments, specifying a file
1906+
descriptor instead of a path.
1907+
1908+
1909+
.. class:: stat_result
1910+
1911+
Object whose attributes correspond roughly to the members of the
1912+
:c:type:`stat` structure. It is used for the result of :func:`os.stat`,
1913+
:func:`os.fstat` and :func:`os.lstat`.
1914+
1915+
Attributes:
1916+
1917+
.. attribute:: st_mode
1918+
1919+
File mode: file type and file mode bits (permissions).
1920+
1921+
.. attribute:: st_ino
1922+
1923+
Inode number.
1924+
1925+
.. attribute:: st_dev
1926+
1927+
Identifier of the device on which this file resides.
1928+
1929+
.. attribute:: st_nlink
1930+
1931+
Number of hard links.
1932+
1933+
.. attribute:: st_uid
1934+
1935+
User identifier of the file owner.
1936+
1937+
.. attribute:: st_gid
1938+
1939+
Group identifier of the file owner.
1940+
1941+
.. attribute:: st_size
1942+
1943+
Size of the file in bytes, if it is a regular file or a symbolic link.
1944+
The size of a symbolic link is the length of the pathname it contains,
1945+
without a terminating null byte.
1946+
1947+
Timestamps:
1948+
1949+
.. attribute:: st_atime
1950+
1951+
Time of most recent access expressed in seconds.
1952+
1953+
.. attribute:: st_mtime
1954+
1955+
Time of most recent content modification expressed in seconds.
1956+
1957+
.. attribute:: st_ctime
19031958

1904-
* :attr:`st_file_attributes` - Windows file attribute bits (see the
1905-
``FILE_ATTRIBUTE_*`` constants in the :mod:`stat` module)
1959+
Platform dependent:
1960+
1961+
* the time of most recent metadata change on Unix,
1962+
* the time of creation on Windows, expressed in seconds.
1963+
1964+
.. attribute:: st_atime_ns
1965+
1966+
Time of most recent access expressed in nanoseconds as an integer.
1967+
1968+
.. attribute:: st_mtime_ns
1969+
1970+
Time of most recent content modification expressed in nanoseconds as an
1971+
integer.
1972+
1973+
.. attribute:: st_ctime_ns
1974+
1975+
Platform dependent:
1976+
1977+
* the time of most recent metadata change on Unix,
1978+
* the time of creation on Windows, expressed in nanoseconds as an
1979+
integer.
1980+
1981+
See also the :func:`stat_float_times` function.
19061982

19071983
.. note::
19081984

@@ -1912,6 +1988,7 @@ features:
19121988
or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and
19131989
:attr:`st_atime` has only 1-day resolution. See your operating system
19141990
documentation for details.
1991+
19151992
Similarly, although :attr:`st_atime_ns`, :attr:`st_mtime_ns`,
19161993
and :attr:`st_ctime_ns` are always expressed in nanoseconds, many
19171994
systems do not provide nanosecond precision. On systems that do
@@ -1921,41 +1998,77 @@ features:
19211998
If you need the exact timestamps you should always use
19221999
:attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`.
19232000

1924-
For backward compatibility, the return value of :func:`~os.stat` is also
1925-
accessible as a tuple of at least 10 integers giving the most important (and
1926-
portable) members of the :c:type:`stat` structure, in the order
1927-
:attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`,
1928-
:attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`,
1929-
:attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by
1930-
some implementations.
2001+
On some Unix systems (such as Linux), the following attributes may also be
2002+
available:
19312003

1932-
This function can support :ref:`specifying a file descriptor <path_fd>` and
1933-
:ref:`not following symlinks <follow_symlinks>`.
2004+
.. attribute:: st_blocks
19342005

1935-
.. index:: module: stat
2006+
Number of 512-byte blocks allocated for file.
2007+
This may be smaller than :attr:`st_size`/512 when the file has holes.
19362008

1937-
The standard module :mod:`stat` defines functions and constants that are useful
1938-
for extracting information from a :c:type:`stat` structure. (On Windows, some
1939-
items are filled with dummy values.)
2009+
.. attribute:: st_blksize
19402010

1941-
Example::
2011+
"Preferred" blocksize for efficient file system I/O. Writing to a file in
2012+
smaller chunks may cause an inefficient read-modify-rewrite.
19422013

1943-
>>> import os
1944-
>>> statinfo = os.stat('somefile.txt')
1945-
>>> statinfo
1946-
posix.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
1947-
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
1948-
st_mtime=1297230027, st_ctime=1297230027)
1949-
>>> statinfo.st_size
1950-
264
2014+
.. attribute:: st_rdev
19512015

1952-
Availability: Unix, Windows.
2016+
Type of device if an inode device.
2017+
2018+
.. attribute:: st_flags
2019+
2020+
User defined flags for file.
2021+
2022+
On other Unix systems (such as FreeBSD), the following attributes may be
2023+
available (but may be only filled out if root tries to use them):
2024+
2025+
.. attribute:: st_gen
2026+
2027+
File generation number.
2028+
2029+
.. attribute:: st_birthtime
2030+
2031+
Time of file creation.
2032+
2033+
On Mac OS systems, the following attributes may also be available:
2034+
2035+
.. attribute:: st_rsize
2036+
2037+
Real size of the file.
2038+
2039+
.. attribute:: st_creator
2040+
2041+
Creator of the file.
2042+
2043+
.. attribute:: st_type
2044+
2045+
File type.
2046+
2047+
On Windows systems, the following attribute is also available:
2048+
2049+
.. attribute:: st_file_attributes
2050+
2051+
Windows file attributes: ``dwFileAttributes`` member of the
2052+
``BY_HANDLE_FILE_INFORMATION`` structure returned by
2053+
:c:func:`GetFileInformationByHandle`. See the ``FILE_ATTRIBUTE_*``
2054+
constants in the :mod:`stat` module.
2055+
2056+
The standard module :mod:`stat` defines functions and constants that are
2057+
useful for extracting information from a :c:type:`stat` structure. (On
2058+
Windows, some items are filled with dummy values.)
2059+
2060+
For backward compatibility, a :class:`stat_result` instance is also
2061+
accessible as a tuple of at least 10 integers giving the most important (and
2062+
portable) members of the :c:type:`stat` structure, in the order
2063+
:attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`,
2064+
:attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`,
2065+
:attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by
2066+
some implementations. For compatibility with older Python versions,
2067+
accessing :class:`stat_result` as a tuple always returns integers.
19532068

19542069
.. versionadded:: 3.3
1955-
Added the *dir_fd* and *follow_symlinks* arguments,
1956-
specifying a file descriptor instead of a path,
1957-
and the :attr:`st_atime_ns`, :attr:`st_mtime_ns`,
1958-
and :attr:`st_ctime_ns` members.
2070+
Added the :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and
2071+
:attr:`st_ctime_ns` members.
19592072

19602073
.. versionadded:: 3.5
19612074
Added the :attr:`st_file_attributes` member on Windows.

‎Doc/whatsnew/3.5.rst‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -185,11 +185,8 @@ ipaddress
185185
os
186186
--
187187

188-
* :class:`os.stat_result` now has a ``st_file_attributes`` field on Windows,
189-
containing the ``dwFileAttributes`` member of the
190-
``BY_HANDLE_FILE_INFORMATION`` structure returned by
191-
``GetFileInformationByHandle()`` (contributed by Ben Hoyt in
192-
:issue:`21719`).
188+
* :class:`os.stat_result` now has a :attr:`~os.stat_result.st_file_attributes`
189+
attribute on Windows (contributed by Ben Hoyt in :issue:`21719`).
193190

194191
shutil
195192
------

0 commit comments

Comments
 (0)