followlinks/follow_symlinks/symlinks flags unification.

Doc/library/shutil.rst

 :mod:`shutil` --- High-level file operations
 ============================================
 
 .. module:: shutil
    :synopsis: High-level file operations, including copying.
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 .. partly based on the docstrings
 
 .. index::
    single: file; copying
@@ skipping 29 matching lines @@
 
    Copy the contents of the file-like object *fsrc* to the file-like object *fdst*.
    The integer *length*, if given, is the buffer size. In particular, a negative
    *length* value means to copy the data without looping over the source data in
    chunks; by default the data is read in chunks to avoid uncontrolled memory
    consumption. Note that if the current file position of the *fsrc* object is not
    0, only the contents from the current file position to the end of the file will
    be copied.
 
 
-.. function:: copyfile(src, dst, symlinks=False)
+.. function:: copyfile(src, dst, *, follow_symlinks=True)
 
    Copy the contents (no metadata) of the file named *src* to a file named
    *dst* and return *dst*.  *dst* must be the complete target file name; look at
    :func:`shutil.copy` for a copy that accepts a target directory path.  If
    *src* and *dst* are the same files, :exc:`Error` is raised.
 
    The destination location must be writable; otherwise,  an :exc:`OSError` exception
    will be raised. If *dst* already exists, it will be replaced.   Special files
    such as character or block devices and pipes cannot be copied with this
    function.  *src* and *dst* are path names given as strings.
 
-   If *symlinks* is true and *src* is a symbolic link, a new symbolic link will
+   If *follow_symlinks* is false and *src* is a symbolic link, a new symbolic link will
    be created instead of copying the file *src* points to.
 
    .. versionchanged:: 3.3
       :exc:`IOError` used to be raised instead of :exc:`OSError`.
-      Added *symlinks* argument.
+      Added *follow_symlinks* argument.
 
    .. versionchanged:: 3.3
       Added return of the *dst*.
 
-.. function:: copymode(src, dst, symlinks=False)
+.. function:: copymode(src, dst, *, follow_symlinks=True)
 
    Copy the permission bits from *src* to *dst*.  The file contents, owner, and
    group are unaffected.  *src* and *dst* are path names given as strings.  If
-   *symlinks* is true, *src* a symbolic link and the operating system supports
+   *follow_symlinks* is false, *src* a symbolic link and the operating system supports
    modes for symbolic links (for example BSD-based ones), the mode of the link
    will be copied.
 
    .. versionchanged:: 3.3
-      Added *symlinks* argument.
-
-.. function:: copystat(src, dst, symlinks=False)
+      Added *follow_symlinks* argument.
+
+.. function:: copystat(src, dst, *, follow_symlinks=True)
 
    Copy the permission bits, last access time, last modification time, and flags
    from *src* to *dst*.  The file contents, owner, and group are unaffected.  *src*
    and *dst* are path names given as strings.  If *src* and *dst* are both
-   symbolic links and *symlinks* true, the stats of the link will be copied as
+   symbolic links and *follow_symlinks* false, the stats of the link will be copied as
    far as the platform allows.
 
    .. versionchanged:: 3.3
-      Added *symlinks* argument.
-
-.. function:: copy(src, dst, symlinks=False)
+      Added *follow_symlinks* argument.
+
+.. function:: copy(src, dst, *, follow_symlinks=True)
 
    Copy the file *src* to the file or directory *dst* and return the file's
    destination.  If *dst* is a directory, a
    file with the same basename as *src*  is created (or overwritten) in the
    directory specified.  Permission bits are copied.  *src* and *dst* are path
-   names given as strings.  If *symlinks* is true, symbolic links won't be
+   names given as strings.  If *follow_symlinks* is false, symbolic links won't be
    followed but recreated instead -- this resembles GNU's :program:`cp -P`.
 
    .. versionchanged:: 3.3
-      Added *symlinks* argument.
+      Added *follow_symlinks* argument.
 
    .. versionchanged:: 3.3
       Added return of the *dst*.
 
-.. function:: copy2(src, dst, symlinks=False)
+.. function:: copy2(src, dst, *, follow_symlinks=True)
 
    Similar to :func:`shutil.copy`, including that the destination is
    returned, but metadata is copied as well. This is
-   similar to the Unix command :program:`cp -p`.  If *symlinks* is true,
+   similar to the Unix command :program:`cp -p`.  If *follow_symlinks* is false,
    symbolic links won't be followed but recreated instead -- this resembles
    GNU's :program:`cp -P`.
 
    .. versionchanged:: 3.3
-      Added *symlinks* argument, try to copy extended file system attributes
+      Added *follow_symlinks* argument, try to copy extended file system attributes
       too (currently Linux only).
 
    .. versionchanged:: 3.3
       Added return of the *dst*.
 
 .. function:: ignore_patterns(\*patterns)
 
    This factory function creates a function that can be used as a callable for
    :func:`copytree`\'s *ignore* argument, ignoring files and directories that
    match one of the glob-style *patterns* provided.  See the example below.
@@ skipping 409 matching lines @@
    size used by many terminal emulators.
 
    The value returned is a named tuple of type :class:`os.terminal_size`.
 
    See also: The Single UNIX Specification, Version 2,
    `Other Environment Variables`_.
 
 .. _`Other Environment Variables`:
    http://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003