Issue 14800: add comments explaining stat.py constants + docstring for S_* functions.

1 files changed, 51 insertions, 38 deletions

diff --git a/Lib/stat.py b/Lib/stat.py
index 78ccd5e..0f29498 100644
--- a/Lib/stat.py
+++ b/Lib/stat.py
@@ -19,78 +19,91 @@ ST_CTIME = 9
 # Extract bits from the mode
 
 def S_IMODE(mode):
+    """Return the portion of the file's mode that can be set by
+    os.chmod().
+    """
     return mode & 0o7777
 
 def S_IFMT(mode):
+    """Return the portion of the file's mode that describes the
+    file type.
+    """
     return mode & 0o170000
 
 # Constants used as S_IFMT() for various file types
 # (not all are implemented on all systems)
 
-S_IFDIR  = 0o040000
-S_IFCHR  = 0o020000
-S_IFBLK  = 0o060000
-S_IFREG  = 0o100000
-S_IFIFO  = 0o010000
-S_IFLNK  = 0o120000
-S_IFSOCK = 0o140000
+S_IFDIR  = 0o040000  # directory
+S_IFCHR  = 0o020000  # character device
+S_IFBLK  = 0o060000  # block device
+S_IFREG  = 0o100000  # regular file
+S_IFIFO  = 0o010000  # fifo (named pipe)
+S_IFLNK  = 0o120000  # symbolic link
+S_IFSOCK = 0o140000  # socket file
 
 # Functions to test for each file type
 
 def S_ISDIR(mode):
+    """Return True if mode is from a directory."""
     return S_IFMT(mode) == S_IFDIR
 
 def S_ISCHR(mode):
+    """Return True if mode is from a character special device file."""
     return S_IFMT(mode) == S_IFCHR
 
 def S_ISBLK(mode):
+    """Return True if mode is from a block special device file."""
     return S_IFMT(mode) == S_IFBLK
 
 def S_ISREG(mode):
+    """Return True if mode is from a regular file."""
     return S_IFMT(mode) == S_IFREG
 
 def S_ISFIFO(mode):
+    """Return True if mode is from a FIFO (named pipe)."""
     return S_IFMT(mode) == S_IFIFO
 
 def S_ISLNK(mode):
+    """Return True if mode is from a symbolic link."""
     return S_IFMT(mode) == S_IFLNK
 
 def S_ISSOCK(mode):
+    """Return True if mode is from a socket."""
     return S_IFMT(mode) == S_IFSOCK
 
 # Names for permission bits
 
-S_ISUID = 0o4000
-S_ISGID = 0o2000
-S_ENFMT = S_ISGID
-S_ISVTX = 0o1000
-S_IREAD = 0o0400
-S_IWRITE = 0o0200
-S_IEXEC = 0o0100
-S_IRWXU = 0o0700
-S_IRUSR = 0o0400
-S_IWUSR = 0o0200
-S_IXUSR = 0o0100
-S_IRWXG = 0o0070
-S_IRGRP = 0o0040
-S_IWGRP = 0o0020
-S_IXGRP = 0o0010
-S_IRWXO = 0o0007
-S_IROTH = 0o0004
-S_IWOTH = 0o0002
-S_IXOTH = 0o0001
+S_ISUID = 0o4000  # set UID bit
+S_ISGID = 0o2000  # set GID bit
+S_ENFMT = S_ISGID # file locking enforcement
+S_ISVTX = 0o1000  # sticky bit
+S_IREAD = 0o0400  # Unix V7 synonym for S_IRUSR
+S_IWRITE = 0o0200 # Unix V7 synonym for S_IWUSR
+S_IEXEC = 0o0100  # Unix V7 synonym for S_IXUSR
+S_IRWXU = 0o0700  # mask for owner permissions
+S_IRUSR = 0o0400  # read by owner
+S_IWUSR = 0o0200  # write by owner
+S_IXUSR = 0o0100  # execute by owner
+S_IRWXG = 0o0070  # mask for group permissions
+S_IRGRP = 0o0040  # read by group
+S_IWGRP = 0o0020  # write by group
+S_IXGRP = 0o0010  # execute by group
+S_IRWXO = 0o0007  # mask for others (not in group) permissions
+S_IROTH = 0o0004  # read by others
+S_IWOTH = 0o0002  # write by others
+S_IXOTH = 0o0001  # execute by others
 
 # Names for file flags
 
-UF_NODUMP    = 0x00000001
-UF_IMMUTABLE = 0x00000002
-UF_APPEND    = 0x00000004
-UF_OPAQUE    = 0x00000008
-UF_NOUNLINK  = 0x00000010
-UF_COMPRESSED = 0x00000020  # OS X: file is hfs-compressed
-UF_HIDDEN    = 0x00008000   # OS X: file should not be displayed
-SF_ARCHIVED  = 0x00010000
-SF_IMMUTABLE = 0x00020000
-SF_APPEND    = 0x00040000
-SF_NOUNLINK  = 0x00100000
-SF_SNAPSHOT  = 0x00200000
+UF_NODUMP    = 0x00000001  # do not dump file
+UF_IMMUTABLE = 0x00000002  # file may not be changed
+UF_APPEND    = 0x00000004  # file may only be appended to
+UF_OPAQUE    = 0x00000008  # directory is opaque when viewed through a union stack
+UF_NOUNLINK  = 0x00000010  # file may not be renamed or deleted
+UF_COMPRESSED = 0x00000020 # OS X: file is hfs-compressed
+UF_HIDDEN    = 0x00008000  # OS X: file should not be displayed
+SF_ARCHIVED  = 0x00010000  # file may be archived
+SF_IMMUTABLE = 0x00020000  # file may not be changed
+SF_APPEND    = 0x00040000  # file may only be appended to
+SF_NOUNLINK  = 0x00100000  # file may not be renamed or deleted
+SF_SNAPSHOT  = 0x00200000  # file is a snapshot file