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

Skip to content

Commit 6d4f4fe

Browse files
vstinnervstinner
committed
Issue #21813: Enhance documentation of the os.stat_result class.
1 parent a3c80ce commit 6d4f4fe

1 file changed

Lines changed: 182 additions & 73 deletions

File tree

‎Doc/library/os.rst‎

Lines changed: 182 additions & 73 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

@@ -1570,17 +1576,25 @@ features:
15701576
Added support for specifying an open file descriptor for *path*.
15711577

15721578

1573-
.. function:: lstat(path, *, dir_fd=None)
1579+
.. function:: lstat(path, \*, dir_fd=None)
15741580

15751581
Perform the equivalent of an :c:func:`lstat` system call on the given path.
1576-
Similar to :func:`~os.stat`, but does not follow symbolic links. On
1577-
platforms that do not support symbolic links, this is an alias for
1578-
:func:`~os.stat`. As of Python 3.3, this is equivalent to ``os.stat(path,
1579-
dir_fd=dir_fd, follow_symlinks=False)``.
1582+
Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
1583+
:class:`stat_result` object.
1584+
1585+
On platforms that do not support symbolic links, this is an alias for
1586+
:func:`~os.stat`.
1587+
1588+
As of Python 3.3, this is equivalent to ``os.stat(path, dir_fd=dir_fd,
1589+
follow_symlinks=False)``.
15801590

15811591
This function can also support :ref:`paths relative to directory descriptors
15821592
<dir_fd>`.
15831593

1594+
.. seealso::
1595+
1596+
The :func:`stat` function.
1597+
15841598
.. versionchanged:: 3.2
15851599
Added support for Windows 6.0 (Vista) symbolic links.
15861600

@@ -1847,49 +1861,116 @@ features:
18471861
The *dir_fd* parameter.
18481862

18491863

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

1880-
On some Unix systems (such as Linux), the following attributes may also be
1881-
available:
1866+
Get the status of a file or a file descriptor. Perform the equivalent of a
1867+
:c:func:`stat` system call on the given path. *path* may be specified as
1868+
either a string or as an open file descriptor. Return a :class:`stat_result`
1869+
object.
18821870

1883-
* :attr:`st_blocks` - number of 512-byte blocks allocated for file
1884-
* :attr:`st_blksize` - filesystem blocksize for efficient file system I/O
1885-
* :attr:`st_rdev` - type of device if an inode device
1886-
* :attr:`st_flags` - user defined flags for file
1871+
This function normally follows symlinks; to stat a symlink add the argument
1872+
``follow_symlinks=False``, or use :func:`lstat`.
18871873

1888-
On other Unix systems (such as FreeBSD), the following attributes may be
1889-
available (but may be only filled out if root tries to use them):
1874+
This function can support :ref:`specifying a file descriptor <path_fd>` and
1875+
:ref:`not following symlinks <follow_symlinks>`.
1876+
1877+
.. index:: module: stat
1878+
1879+
Example::
1880+
1881+
>>> import os
1882+
>>> statinfo = os.stat('somefile.txt')
1883+
>>> statinfo
1884+
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
1885+
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
1886+
st_mtime=1297230027, st_ctime=1297230027)
1887+
>>> statinfo.st_size
1888+
264
1889+
1890+
Availability: Unix, Windows.
1891+
1892+
.. seealso::
1893+
1894+
:func:`fstat` and :func:`lstat` functions.
1895+
1896+
.. versionadded:: 3.3
1897+
Added the *dir_fd* and *follow_symlinks* arguments, specifying a file
1898+
descriptor instead of a path.
1899+
1900+
1901+
.. class:: stat_result
1902+
1903+
Object whose attributes correspond roughly to the members of the
1904+
:c:type:`stat` structure. It is used for the result of :func:`os.stat`,
1905+
:func:`os.fstat` and :func:`os.lstat`.
1906+
1907+
Attributes:
1908+
1909+
.. attribute:: st_mode
1910+
1911+
File mode: file type and file mode bits (permissions).
1912+
1913+
.. attribute:: st_ino
1914+
1915+
Inode number.
1916+
1917+
.. attribute:: st_dev
1918+
1919+
Identifier of the device on which this file resides.
1920+
1921+
.. attribute:: st_nlink
1922+
1923+
Number of hard links.
1924+
1925+
.. attribute:: st_uid
1926+
1927+
User identifier of the file owner.
1928+
1929+
.. attribute:: st_gid
1930+
1931+
Group identifier of the file owner.
1932+
1933+
.. attribute:: st_size
1934+
1935+
Size of the file in bytes, if it is a regular file or a symbolic link.
1936+
The size of a symbolic link is the length of the pathname it contains,
1937+
without a terminating null byte.
1938+
1939+
Timestamps:
1940+
1941+
.. attribute:: st_atime
1942+
1943+
Time of most recent access expressed in seconds.
18901944

1891-
* :attr:`st_gen` - file generation number
1892-
* :attr:`st_birthtime` - time of file creation
1945+
.. attribute:: st_mtime
1946+
1947+
Time of most recent content modification expressed in seconds.
1948+
1949+
.. attribute:: st_ctime
1950+
1951+
Platform dependent:
1952+
1953+
* the time of most recent metadata change on Unix,
1954+
* the time of creation on Windows, expressed in seconds.
1955+
1956+
.. attribute:: st_atime_ns
1957+
1958+
Time of most recent access expressed in nanoseconds as an integer.
1959+
1960+
.. attribute:: st_mtime_ns
1961+
1962+
Time of most recent content modification expressed in nanoseconds as an
1963+
integer.
1964+
1965+
.. attribute:: st_ctime_ns
1966+
1967+
Platform dependent:
1968+
1969+
* the time of most recent metadata change on Unix,
1970+
* the time of creation on Windows, expressed in nanoseconds as an
1971+
integer.
1972+
1973+
See also the :func:`stat_float_times` function.
18931974

18941975
.. note::
18951976

@@ -1899,6 +1980,7 @@ features:
18991980
or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and
19001981
:attr:`st_atime` has only 1-day resolution. See your operating system
19011982
documentation for details.
1983+
19021984
Similarly, although :attr:`st_atime_ns`, :attr:`st_mtime_ns`,
19031985
and :attr:`st_ctime_ns` are always expressed in nanoseconds, many
19041986
systems do not provide nanosecond precision. On systems that do
@@ -1908,41 +1990,68 @@ features:
19081990
If you need the exact timestamps you should always use
19091991
:attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`.
19101992

1911-
For backward compatibility, the return value of :func:`~os.stat` is also
1912-
accessible as a tuple of at least 10 integers giving the most important (and
1913-
portable) members of the :c:type:`stat` structure, in the order
1914-
:attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`,
1915-
:attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`,
1916-
:attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by
1917-
some implementations.
1993+
On some Unix systems (such as Linux), the following attributes may also be
1994+
available:
19181995

1919-
This function can support :ref:`specifying a file descriptor <path_fd>` and
1920-
:ref:`not following symlinks <follow_symlinks>`.
1996+
.. attribute:: st_blocks
19211997

1922-
.. index:: module: stat
1998+
Number of 512-byte blocks allocated for file.
1999+
This may be smaller than :attr:`st_size`/512 when the file has holes.
19232000

1924-
The standard module :mod:`stat` defines functions and constants that are useful
1925-
for extracting information from a :c:type:`stat` structure. (On Windows, some
1926-
items are filled with dummy values.)
2001+
.. attribute:: st_blksize
19272002

1928-
Example::
2003+
"Preferred" blocksize for efficient file system I/O. Writing to a file in
2004+
smaller chunks may cause an inefficient read-modify-rewrite.
19292005

1930-
>>> import os
1931-
>>> statinfo = os.stat('somefile.txt')
1932-
>>> statinfo
1933-
posix.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
1934-
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
1935-
st_mtime=1297230027, st_ctime=1297230027)
1936-
>>> statinfo.st_size
1937-
264
2006+
.. attribute:: st_rdev
19382007

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

19412052
.. versionadded:: 3.3
1942-
Added the *dir_fd* and *follow_symlinks* arguments,
1943-
specifying a file descriptor instead of a path,
1944-
and the :attr:`st_atime_ns`, :attr:`st_mtime_ns`,
1945-
and :attr:`st_ctime_ns` members.
2053+
Added the :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and
2054+
:attr:`st_ctime_ns` members.
19462055

19472056

19482057
.. function:: stat_float_times([newvalue])

0 commit comments

Comments
 (0)