Merged revisions 87136,87221,87256,87337-87338,87571,87839,88164 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k


........
  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.
........
  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.
........
  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.
    [compileall.py changes not backported.]
........
  r87571 | r.david.murray | 2010-12-29 14:06:48 -0500 (Wed, 29 Dec 2010) | 2 lines

  Fix same typo in docs.
........
  r87839 | r.david.murray | 2011-01-07 16:57:25 -0500 (Fri, 07 Jan 2011) | 9 lines

  Fix formatting of values with embedded newlines when rfc2047 encoding

  Before this patch if a value being encoded had an embedded newline,
  the line following the newline would have no leading whitespace,
  and the whitespace it did have was encoded into the word.  Now
  the existing whitespace gets turned into a blank, the way it does
  in other header reformatting, and the _continuation_ws gets added
  at the beginning of the encoded line.
........
  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.
........

1 files changed, 55 insertions, 37 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index d5aa6fe..cf012ff 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -534,7 +534,7 @@ as internal buffering of data.
 
 .. 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.
 
@@ -952,9 +952,10 @@ Files and Directories
 
 .. 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])
@@ -1138,56 +1139,73 @@ Files and Directories
 
 .. 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, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732)
-      >>> statinfo.st_size
-      926
-      >>>
+   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)
 
    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`.
 
-   .. index:: module: stat
+   * :attr:`st_rsize`
+   * :attr:`st_creator`
+   * :attr:`st_type`
+
+   .. note::
+
+      The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
+      :attr:`st_ctime` members depends on the operating system and the file system.
+      For example, on Windows systems using the FAT or FAT32 file systems,
+      :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:`stat` is also accessible
+   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.)
 
-   .. note::
+   Example::
 
-      The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
-      :attr:`st_ctime` members depends on the operating system and the file system.
-      For example, on Windows systems using the FAT or FAT32 file systems,
-      :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
-      resolution.  See your operating system documentation for details.
+      >>> 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.
 
@@ -1195,7 +1213,7 @@ Files and Directories
 .. 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.
 
@@ -1255,8 +1273,8 @@ Files and Directories
    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`.
 
    Availability: Unix, Windows.