followlinks/follow_symlinks/symlinks flags unification.

Lib/shutil.py

 """Utility functions for copying and archiving files and directory trees.
 
 XXX The functions here don't copy the resource fork or other metadata on Mac.
 
 """
 
 import os
 import sys
 import stat
 from os.path import abspath
@@ skipping 64 matching lines @@
     if hasattr(os.path, 'samefile'):
         try:
             return os.path.samefile(src, dst)
         except OSError:
             return False
 
     # All other platforms: check for same pathname.
     return (os.path.normcase(os.path.abspath(src)) ==
             os.path.normcase(os.path.abspath(dst)))
 
-def copyfile(src, dst, follow_symlinks=True):

[larry, 2012/07/01 17:44:36]

follow_symlinks should always be keyword-only.  Please add a "*," between dst
and follow_symlinks, here and in all other methods in this file.

+def copyfile(src, dst, *, follow_symlinks=True):
     """Copy data from src to dst.
 
     If optional flag `follow_symlinks` is not set and `src` is a symbolic link, a new

[larry, 2012/07/01 17:44:36]

Please change this paragraph to:

"""
If follow_symlinks is False and src is a symbolic link,
dst will be created as a copy of that symbolic link
(rather than the file it points to).
"""

     symlink will be created instead of copying the file it points to.
 
     """
     if _samefile(src, dst):
         raise Error("`%s` and `%s` are the same file" % (src, dst))
 
     for fn in [src, dst]:
         try:
             st = os.stat(fn)
         except OSError:
             # File most likely does not exist
             pass
         else:
             # XXX What about other special files? (sockets, devices...)
             if stat.S_ISFIFO(st.st_mode):
                 raise SpecialFileError("`%s` is a named pipe" % fn)
 
     if not follow_symlinks and os.path.islink(src):
         os.symlink(os.readlink(src), dst)
     else:
         with open(src, 'rb') as fsrc:
             with open(dst, 'wb') as fdst:
                 copyfileobj(fsrc, fdst)
     return dst
 
-def copymode(src, dst, follow_symlinks=True):
+def copymode(src, dst, *, follow_symlinks=True):
     """Copy mode bits from src to dst.
 
     If the optional flag `follow_symlinks` is not set, symlinks aren't followed if and

[larry, 2012/07/01 17:44:36]

Please change this paragraph to:

"""
If follow_symlinks is False, and src and dst are both
symbolic links, copymode will change the mode of the dst
symbolic link rather than the file it points to.  (This
functionality is not available on all platforms.)
"""

Let's move the specific details about lchmod into the full docs.

     only if both `src` and `dst` are symlinks. If `lchmod` isn't available (eg.
     Linux), in these cases, this method does nothing.
 
     """
     if not follow_symlinks and os.path.islink(src) and os.path.islink(dst):
         if hasattr(os, 'lchmod'):
             stat_func, chmod_func = os.lstat, os.lchmod
         else:
             return
     elif hasattr(os, 'chmod'):
         stat_func, chmod_func = os.stat, os.chmod
     else:
         return
 
     st = stat_func(src)
     chmod_func(dst, stat.S_IMODE(st.st_mode))
 
-def copystat(src, dst, follow_symlinks=True):
+def copystat(src, dst, *, follow_symlinks=True):
     """Copy all stat info (mode bits, atime, mtime, flags) from src to dst.
 
     If the optional flag `follow_symlinks` is not set, symlinks aren't followed if and

[larry, 2012/07/01 17:44:36]

Please change to:

"""
If follow_symlinks is False, and src and dst are both
symbolic links, copystat will read the information from
the src symbolic link and write it to the dst symbolic
link, rather than reading from and writing to the files
they point to.  (This functionality is not available on
all platforms.)
"""

     only if both `src` and `dst` are symlinks.
 
     """
     def _nop(*args, ns=None, follow_symlinks=None):
         pass
 
     # follow symlinks (aka don't not follow symlinks)
     follow = follow_symlinks or not (os.path.islink(src) and os.path.islink(dst))
     if follow:
         # use the real function if it exists
@@ skipping 30 matching lines @@
         try:
             lookup("chflags")(dst, st.st_flags, follow_symlinks=follow)
         except OSError as why:
             for err in 'EOPNOTSUPP', 'ENOTSUP':
                 if hasattr(errno, err) and why.errno == getattr(errno, err):
                     break
             else:
                 raise
 
 if hasattr(os, 'listxattr'):
-    def _copyxattr(src, dst, follow_symlinks=True):
+    def _copyxattr(src, dst, *, follow_symlinks=True):
         """Copy extended filesystem attributes from `src` to `dst`.
 
         Overwrite existing attributes.
 
         If the optional flag `follow_symlinks` is not set, symlinks won't be followed.
 
         """
 
         for name in os.listxattr(src, follow_symlinks=follow_symlinks):
             try:
                 value = os.getxattr(src, name, follow_symlinks=follow_symlinks)
                 os.setxattr(dst, name, value, follow_symlinks=follow_symlinks)
             except OSError as e:
                 if e.errno not in (errno.EPERM, errno.ENOTSUP, errno.ENODATA):
                     raise
 else:
     def _copyxattr(*args, **kwargs):
         pass
 
-def copy(src, dst, follow_symlinks=True):
+def copy(src, dst, *, follow_symlinks=True):
     """Copy data and mode bits ("cp src dst"). Return the file's destination.
 
     The destination may be a directory.
 
     If the optional flag `follow_symlinks` is not set, symlinks won't be followed. This
     resembles GNU's "cp -P src dst".
 
     """
     if os.path.isdir(dst):
         dst = os.path.join(dst, os.path.basename(src))
     copyfile(src, dst, follow_symlinks=follow_symlinks)
     copymode(src, dst, follow_symlinks=follow_symlinks)
     return dst
 
-def copy2(src, dst, follow_symlinks=True):
+def copy2(src, dst, *, follow_symlinks=True):
     """Copy data and all stat info ("cp -p src dst"). Return the file's
     destination."
 
     The destination may be a directory.
 
     If the optional flag `follow_symlinks` is not set, symlinks won't be followed. This
     resembles GNU's "cp -P src dst".
 
     """
     if os.path.isdir(dst):
@@ skipping 858 matching lines @@
     seen = set()
     for dir in path:
         dir = os.path.normcase(dir)
         if not dir in seen:
             seen.add(dir)
             for thefile in files:
                 name = os.path.join(dir, thefile)
                 if _access_check(name, mode):
                     return name
     return None