From efd8bab40381b9ffbf2dae72444fb88bb8193ec9 Mon Sep 17 00:00:00 2001
From: R David Murray <rdmurray@bitdance.com>
Date: Thu, 10 Mar 2011 17:57:35 -0500
Subject: [PATCH] #10999: Add missing documentation for chflags constants to
 stat module docs

Patch by Michal Nowikowski.
---
 Doc/library/os.rst   | 20 +++++-----
 Doc/library/stat.rst | 88 +++++++++++++++++++++++++++++++++-----------
 Misc/ACKS            |  1 +
 3 files changed, 77 insertions(+), 32 deletions(-)

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index e97cf809144..b16fb1fa364 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -990,16 +990,16 @@ Files and Directories
    Set the flags of *path* to the numeric *flags*. *flags* may take a combination
    (bitwise OR) of the following values (as defined in the :mod:`stat` module):
 
-   * ``UF_NODUMP``
-   * ``UF_IMMUTABLE``
-   * ``UF_APPEND``
-   * ``UF_OPAQUE``
-   * ``UF_NOUNLINK``
-   * ``SF_ARCHIVED``
-   * ``SF_IMMUTABLE``
-   * ``SF_APPEND``
-   * ``SF_NOUNLINK``
-   * ``SF_SNAPSHOT``
+   * :data:`stat.UF_NODUMP`
+   * :data:`stat.UF_IMMUTABLE`
+   * :data:`stat.UF_APPEND`
+   * :data:`stat.UF_OPAQUE`
+   * :data:`stat.UF_NOUNLINK`
+   * :data:`stat.SF_ARCHIVED`
+   * :data:`stat.SF_IMMUTABLE`
+   * :data:`stat.SF_APPEND`
+   * :data:`stat.SF_NOUNLINK`
+   * :data:`stat.SF_SNAPSHOT`
 
    Availability: Unix.
 
diff --git a/Doc/library/stat.rst b/Doc/library/stat.rst
index a48a02dbf8c..417ba8db04d 100644
--- a/Doc/library/stat.rst
+++ b/Doc/library/stat.rst
@@ -73,6 +73,34 @@ for each test.  These are also useful when checking for information about a file
 that isn't handled by :mod:`os.path`, like the tests for block and character
 devices.
 
+Example::
+
+   import os, sys
+   from stat import *
+
+   def walktree(top, callback):
+       '''recursively descend the directory tree rooted at top,
+          calling the callback function for each regular file'''
+
+       for f in os.listdir(top):
+           pathname = os.path.join(top, f)
+           mode = os.stat(pathname)[ST_MODE]
+           if S_ISDIR(mode):
+               # It's a directory, recurse into it
+               walktree(pathname, callback)
+           elif S_ISREG(mode):
+               # It's a file, call the callback function
+               callback(pathname)
+           else:
+               # Unknown file type, print a message
+               print 'Skipping %s' % pathname
+
+   def visitfile(file):
+       print 'visiting', file
+
+   if __name__ == '__main__':
+       walktree(sys.argv[1], visitfile)
+
 All the variables below are simply symbolic indexes into the 10-tuple returned
 by :func:`os.stat`, :func:`os.fstat` or :func:`os.lstat`.
 
@@ -262,31 +290,47 @@ The following flags can also be used in the *mode* argument of :func:`os.chmod`:
 
    Unix V7 synonym for :data:`S_IXUSR`.
 
-Example::
+The following flags can be used in the *flags* argument of :func:`os.chflags`:
 
-   import os, sys
-   from stat import *
+.. data:: UF_NODUMP
 
-   def walktree(top, callback):
-       '''recursively descend the directory tree rooted at top,
-          calling the callback function for each regular file'''
+   Do not dump the file.
 
-       for f in os.listdir(top):
-           pathname = os.path.join(top, f)
-           mode = os.stat(pathname)[ST_MODE]
-           if S_ISDIR(mode):
-               # It's a directory, recurse into it
-               walktree(pathname, callback)
-           elif S_ISREG(mode):
-               # It's a file, call the callback function
-               callback(pathname)
-           else:
-               # Unknown file type, print a message
-               print 'Skipping %s' % pathname
+.. data:: UF_IMMUTABLE
 
-   def visitfile(file):
-       print 'visiting', file
+   The file may not be changed.
 
-   if __name__ == '__main__':
-       walktree(sys.argv[1], visitfile)
+.. data:: UF_APPEND
+
+   The file may only be appended to.
+
+.. data:: UF_OPAQUE
+
+   The file may not be renamed or deleted.
+
+.. data:: UF_NOUNLINK
+
+   The directory is opaque when viewed through a union stack.
+
+.. data:: SF_ARCHIVED
+
+   The file may be archived.
+
+.. data:: SF_IMMUTABLE
+
+   The file may not be changed.
+
+.. data:: SF_APPEND
+
+   The file may only be appended to.
+
+.. data:: SF_NOUNLINK
+
+   The file may not be renamed or deleted.
+
+.. data:: SF_SNAPSHOT
+
+   The file is a snapshot file.
+
+See the \*BSD or Mac OS systems man page :manpage:`chflags(2)` for more information.
 
diff --git a/Misc/ACKS b/Misc/ACKS
index 3cb7667a3b7..9ec0fc9239f 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -584,6 +584,7 @@ Stefan Norberg
 Tim Northover
 Joe Norton
 Neal Norwitz
+Michal Nowikowski
 Nigel O'Brian
 Kevin O'Connor
 Tim O'Malley