[Python-checkins] peps: PEP 471: Minor change, rename scandir() parameter from "directory" to "path"

[victor.stinner]

http://hg.python.org/peps/rev/c375c79c2d5c
changeset:   5541:c375c79c2d5c
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Tue Sep 02 21:12:14 2014 +0200
summary:
  PEP 471: Minor change, rename scandir() parameter from "directory" to "path"

files:
  pep-0471.txt |  33 +++++++++++++++++----------------
  1 files changed, 17 insertions(+), 16 deletions(-)


diff --git a/pep-0471.txt b/pep-0471.txt
--- a/pep-0471.txt
+++ b/pep-0471.txt
@@ -91,11 +91,11 @@
 module in the standard library, ``scandir``, that takes a single,
 optional string as its argument::
 
-    scandir(directory='.') -> generator of DirEntry objects
+    scandir(path='.') -> generator of DirEntry objects
 
 Like ``listdir``, ``scandir`` calls the operating system's directory
 iteration system calls to get the names of the files in the given
-``directory``, but it's different from ``listdir`` in two ways:
+``path``, but it's different from ``listdir`` in two ways:
 
 * Instead of returning bare filename strings, it returns lightweight
   ``DirEntry`` objects that hold the filename string and provide
@@ -106,16 +106,17 @@
   as a true iterator instead of returning the full list immediately.
 
 ``scandir()`` yields a ``DirEntry`` object for each file and
-sub-directory in ``directory``. Just like ``listdir``, the ``'.'``
+sub-directory in ``path``. Just like ``listdir``, the ``'.'``
 and ``'..'`` pseudo-directories are skipped, and the entries are
 yielded in system-dependent order. Each ``DirEntry`` object has the
 following attributes and methods:
 
-* ``name``: the entry's filename, relative to the ``directory``
+* ``name``: the entry's filename, relative to the scandir ``path``
   argument (corresponds to the return values of ``os.listdir``)
 
 * ``path``: the entry's full path name (not necessarily an absolute
-  path) -- the equivalent of ``os.path.join(directory, entry.name)``
+  path) -- the equivalent of ``os.path.join(scandir_path,
+  entry.name)``
 
 * ``is_dir(*, follow_symlinks=True)``: similar to
   ``pathlib.Path.is_dir()``, but the return value is cached on the
@@ -124,7 +125,7 @@
 
 * ``is_file(*, follow_symlinks=True)``: similar to
   ``pathlib.Path.is_file()``, but the return value is cached on the
-  ``DirEntry`` object; doesn't require a system call in most cases; 
+  ``DirEntry`` object; doesn't require a system call in most cases;
   don't follow symbolic links if ``follow_symlinks`` is False
 
 * ``is_symlink()``: similar to ``pathlib.Path.is_symlink()``, but the
@@ -147,9 +148,9 @@
 first call.
 
 Like the other functions in the ``os`` module, ``scandir()`` accepts
-either a bytes or str object for the ``directory`` parameter, and
+either a bytes or str object for the ``path`` parameter, and
 returns the ``DirEntry.name`` and ``DirEntry.path`` attributes with
-the same type as ``directory``. However, it is *strongly recommended*
+the same type as ``path``. However, it is *strongly recommended*
 to use the str type, as this ensures cross-platform support for
 Unicode filenames. (On Windows, bytes filenames have been deprecated
 since Python 3.3).
@@ -183,10 +184,10 @@
 use of the ``DirEntry.stat()`` method and ``DirEntry.path``
 attribute::
 
-    def get_tree_size(directory):
-        """Return total size of files in directory and subdirs."""
+    def get_tree_size(path):
+        """Return total size of files in given path and subdirs."""
         total = 0
-        for entry in os.scandir(directory):
+        for entry in os.scandir(path):
             if entry.is_dir(follow_symlinks=False):
                 total += get_tree_size(entry.path)
             else:
@@ -256,13 +257,13 @@
 For example, below is a version of the ``get_tree_size()`` example
 shown above, but with fine-grained error handling added::
 
-    def get_tree_size(directory):
-        """Return total size of files in directory and subdirs. If
+    def get_tree_size(path):
+        """Return total size of files in path and subdirs. If
         is_dir() or stat() fails, print an error message to stderr
         and assume zero size (for example, file has been deleted).
         """
         total = 0
-        for entry in os.scandir(directory):
+        for entry in os.scandir(path):
             try:
                 is_dir = entry.is_dir(follow_symlinks=False)
             except OSError as error:
@@ -534,12 +535,12 @@
 ``OSError``) during iteration, leading to a rather ugly, hand-made
 iteration loop::
 
-    it = os.scandir(directory)
+    it = os.scandir(path)
     while True:
         try:
             entry = next(it)
         except OSError as error:
-            handle_error(directory, error)
+            handle_error(path, error)
         except StopIteration:
             break
 

-- 
Repository URL: http://hg.python.org/peps