[Python-checkins] (3.1): #10999: Add missing documentation for chflags constants to stat module docs

Fri Mar 11 00:22:41 CET 2011

http://hg.python.org/cpython/rev/4f9213d3858b
changeset: 68360:4f9213d3858b
branch: 3.1
parent: 68357:f2edf0a7f92f
user: R David Murray <rdmurray at bitdance.com>
date: Thu Mar 10 17:18:33 2011 -0500
summary:
 #10999: Add missing documentation for chflags constants to stat module docs
Patch by Michal Nowikowski.
files:
 Doc/library/os.rst
 Doc/library/stat.rst
 Misc/ACKS

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -842,16 +842,16 @@
 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
--- a/Doc/library/stat.rst
+++ b/Doc/library/stat.rst
@@ -73,6 +73,34 @@
 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 @@
 
 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
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -578,6 +578,7 @@
 Tim Northover
 Joe Norton
 Neal Norwitz
+Michal Nowikowski
 Nigel O'Brian
 Kevin O'Connor
 Tim O'Malley
-- 
Repository URL: http://hg.python.org/cpython
