Merged revisions 86542,87136,87216,87221,87228,87256,87337-87338,87372,87516,87571,88164 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r86542 | r.david.murray | 2010-11-19 22:48:58 -0500 (Fri, 19 Nov 2010) | 2 lines
Make test class name unique so that both test classes run.
........
r87136 | r.david.murray | 2010-12-08 17:53:00 -0500 (Wed, 08 Dec 2010) | 6 lines
Have script_helper._assert_python strip refcount strings from stderr.
This makes the output of the function and those that depend on it
independent of whether or not they are being run under a debug
build.
........
r87216 | r.david.murray | 2010-12-13 17:50:30 -0500 (Mon, 13 Dec 2010) | 2 lines
#10698: fix typo in example.
........
r87221 | r.david.murray | 2010-12-13 19:55:46 -0500 (Mon, 13 Dec 2010) | 4 lines
#10699: fix docstring for tzset: it does not take a parameter
Thanks to Garrett Cooper for the fix.
........
r87228 | r.david.murray | 2010-12-13 21:25:43 -0500 (Mon, 13 Dec 2010) | 2 lines
Turn on regrtest -W (rerun immediately) option for Windows, too.
........
r87256 | r.david.murray | 2010-12-14 21:19:14 -0500 (Tue, 14 Dec 2010) | 2 lines
#10705: document what the values of debuglevel are and mean.
........
r87337 | r.david.murray | 2010-12-17 11:11:40 -0500 (Fri, 17 Dec 2010) | 2 lines
#10559: provide instructions for accessing sys.argv when first mentioned.
........
r87338 | r.david.murray | 2010-12-17 11:29:07 -0500 (Fri, 17 Dec 2010) | 2 lines
#10454: clarify the compileall docs and help messages.
[changes to compileall.py were not backported, only the doc changes]
........
r87372 | r.david.murray | 2010-12-18 11:39:06 -0500 (Sat, 18 Dec 2010) | 2 lines
#10728: the default for printing help is sys.stdout, not stderr.
........
r87516 | r.david.murray | 2010-12-27 15:09:32 -0500 (Mon, 27 Dec 2010) | 5 lines
#7056: runtest and runtest_inner don't use testdir, so drop it from their sigs
I've only tested regular runs and -j runs. If I've broken anything
else I'm sure I'll hear about it sooner or later.
........
r87571 | r.david.murray | 2010-12-29 14:06:48 -0500 (Wed, 29 Dec 2010) | 2 lines
Fix same typo in docs.
........
r88164 | r.david.murray | 2011-01-24 14:34:58 -0500 (Mon, 24 Jan 2011) | 12 lines
#10960: fix 'stat' links, link to lstat from stat, general tidy of stat doc.
Original patch by Michal Nowikowski, with some additions and wording
fixes by me.
I changed the wording from 'Performs a stat system call' to 'Performs
the equivalent of a stat system call', since on Windows there are no
stat/lstat system calls involved. I also extended Michal's breakout
of the attributes into a list to the other paragraphs, and rearranged
the order of the paragraphs in the 'stat' docs to make it flow
better and put it in what I think is a more logical/useful order.
........
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 7378d2e..8e4c53d 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -674,7 +674,7 @@
.. function:: fstat(fd)
- Return status for file descriptor *fd*, like :func:`stat`.
+ Return status for file descriptor *fd*, like :func:`~os.stat`.
Availability: Unix, Windows.
@@ -1114,9 +1114,10 @@
.. function:: lstat(path)
- Like :func:`stat`, but do not follow symbolic links. This is an alias for
- :func:`stat` on platforms that do not support symbolic links, such as
- Windows.
+ Perform the equivalent of an :c:func:`lstat` system call on the given path.
+ Similar to :func:`~os.stat`, but does not follow symbolic links. On
+ platforms that do not support symbolic links, this is an alias for
+ :func:`~os.stat`.
.. function:: mkfifo(path[, mode])
@@ -1314,23 +1315,23 @@
.. function:: stat(path)
- Perform a :cfunc:`stat` system call on the given path. The return value is an
- object whose attributes correspond to the members of the :ctype:`stat`
- structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
- number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
- :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
- :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
- access), :attr:`st_mtime` (time of most recent content modification),
- :attr:`st_ctime` (platform dependent; time of most recent metadata change on
- Unix, or the time of creation on Windows)::
+ Perform the equivalent of a :c:func:`stat` system call on the given path.
+ (This function follows symlinks; to stat a symlink use :func:`lstat`.)
- >>> import os
- >>> statinfo = os.stat('somefile.txt')
- >>> statinfo
- (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
- >>> statinfo.st_size
- 926L
- >>>
+ The return value is an object whose attributes correspond to the members
+ of the :c:type:`stat` structure, namely:
+
+ * :attr:`st_mode` - protection bits,
+ * :attr:`st_ino` - inode number,
+ * :attr:`st_dev` - device,
+ * :attr:`st_nlink` - number of hard links,
+ * :attr:`st_uid` - user id of owner,
+ * :attr:`st_gid` - group id of owner,
+ * :attr:`st_size` - size of file, in bytes,
+ * :attr:`st_atime` - time of most recent access,
+ * :attr:`st_mtime` - time of most recent content modification,
+ * :attr:`st_ctime` - platform dependent; time of most recent metadata change on
+ Unix, or the time of creation on Windows)
.. versionchanged:: 2.3
If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
@@ -1339,31 +1340,30 @@
discussion.
On some Unix systems (such as Linux), the following attributes may also be
- available: :attr:`st_blocks` (number of blocks allocated for file),
- :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
- inode device). :attr:`st_flags` (user defined flags for file).
+ available:
+
+ * :attr:`st_blocks` - number of blocks allocated for file
+ * :attr:`st_blksize` - filesystem blocksize
+ * :attr:`st_rdev` - type of device if an inode device
+ * :attr:`st_flags` - user defined flags for file
On other Unix systems (such as FreeBSD), the following attributes may be
- available (but may be only filled out if root tries to use them): :attr:`st_gen`
- (file generation number), :attr:`st_birthtime` (time of file creation).
+ available (but may be only filled out if root tries to use them):
+
+ * :attr:`st_gen` - file generation number
+ * :attr:`st_birthtime` - time of file creation
On Mac OS systems, the following attributes may also be available:
- :attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.
- On RISCOS systems, the following attributes are also available: :attr:`st_ftype`
- (file type), :attr:`st_attrs` (attributes), :attr:`st_obtype` (object type).
+ * :attr:`st_rsize`
+ * :attr:`st_creator`
+ * :attr:`st_type`
- .. index:: module: stat
+ On RISCOS systems, the following attributes are also available:
- For backward compatibility, the return value of :func:`stat` is also accessible
- as a tuple of at least 10 integers giving the most important (and portable)
- members of the :ctype:`stat` structure, in the order :attr:`st_mode`,
- :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
- :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
- :attr:`st_ctime`. More items may be added at the end by some implementations.
- The standard module :mod:`stat` defines functions and constants that are useful
- for extracting information from a :ctype:`stat` structure. (On Windows, some
- items are filled with dummy values.)
+ * :attr:`st_ftype` (file type)
+ * :attr:`st_attrs` (attributes)
+ * :attr:`st_obtype` (object type).
.. note::
@@ -1373,6 +1373,28 @@
:attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
resolution. See your operating system documentation for details.
+ For backward compatibility, the return value of :func:`~os.stat` is also accessible
+ as a tuple of at least 10 integers giving the most important (and portable)
+ members of the :ctype:`stat` structure, in the order :attr:`st_mode`,
+ :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
+ :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
+ :attr:`st_ctime`. More items may be added at the end by some implementations.
+
+ .. index:: module: stat
+
+ The standard module :mod:`stat` defines functions and constants that are useful
+ for extracting information from a :ctype:`stat` structure. (On Windows, some
+ items are filled with dummy values.)
+
+ Example::
+
+ >>> import os
+ >>> statinfo = os.stat('somefile.txt')
+ >>> statinfo
+ (33188, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732)
+ >>> statinfo.st_size
+ 926
+
Availability: Unix, Windows.
.. versionchanged:: 2.2
@@ -1385,7 +1407,7 @@
.. function:: stat_float_times([newvalue])
Determine whether :class:`stat_result` represents time stamps as float objects.
- If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
+ If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
``False``, future calls return ints. If *newvalue* is omitted, return the
current setting.
@@ -1505,8 +1527,8 @@
respectively. Whether a directory can be given for *path* depends on whether
the operating system implements directories as files (for example, Windows
does not). Note that the exact times you set here may not be returned by a
- subsequent :func:`stat` call, depending on the resolution with which your
- operating system records access and modification times; see :func:`stat`.
+ subsequent :func:`~os.stat` call, depending on the resolution with which your
+ operating system records access and modification times; see :func:`~os.stat`.
.. versionchanged:: 2.0
Added support for ``None`` for *times*.