https://hg.python.org/cpython/rev/f2c68cb17e31 changeset: 100130:f2c68cb17e31 branch: 3.5 parent: 100127:9a31895a1c9d user: Victor Stinner <victor.stinner@gmail.com> date: Sun Jan 31 18:36:41 2016 +0100 summary: Enhance os.scandir() doc Issue #26248, patch written by Ben Hoyt: 1) Clarify that the return values of is_dir()/is_file()/etc are cached separately for follow_symlinks True and False. 2) Be more specific about when the functions require a system call, and how it relates to caching and follow_symlinks. 3) DRY up common stuff between is_dir and is_file by saying "Caching, system calls made, and exceptions raised are as per is_dir" in is_file. 4) Tweak to the first paragraph of docs for is_dir/is_file to simplify: assume the follow_symlinks=True default, then note the follow_symlinks=False non-default case after. files: Doc/library/os.rst | 87 +++++++++++++++++---------------- 1 files changed, 45 insertions(+), 42 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1960,80 +1960,83 @@ Return the inode number of the entry. - The result is cached on the ``DirEntry`` object, use ``os.stat(entry.path, + The result is cached on the ``DirEntry`` object. Use ``os.stat(entry.path, follow_symlinks=False).st_ino`` to fetch up-to-date information. - On Unix, no system call is required. + On the first, uncached call, a system call is required on Windows but + not on Unix. .. method:: is_dir(\*, follow_symlinks=True) - If *follow_symlinks* is ``True`` (the default), return ``True`` if the - entry is a directory or a symbolic link pointing to a directory; - return ``False`` if it is or points to any other kind of file, or if it - doesn't exist anymore. + Return ``True`` if this entry is a directory or a symbolic link pointing + to a directory; return ``False`` if the entry is or points to any other + kind of file, or if it doesn't exist anymore. If *follow_symlinks* is ``False``, return ``True`` only if this entry - is a directory; return ``False`` if it is any other kind of file - or if it doesn't exist anymore. - - The result is cached on the ``DirEntry`` object. Call :func:`os.stat` - along with :func:`stat.S_ISDIR` to fetch up-to-date information. + is a directory (without following symlinks); return ``False`` if the + entry is any other kind of file or if it doesn't exist anymore. + + The result is cached on the ``DirEntry`` object, with a separate cache + for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` along + with :func:`stat.S_ISDIR` to fetch up-to-date information. + + On the first, uncached call, no system call is required in most cases. + Specifically, for non-symlinks, neither Windows or Unix require a system + call, except on certain Unix file systems, such as network file systems, + that return ``dirent.d_type == DT_UNKNOWN``. If the entry is a symlink, + a system call will be required to follow the symlink unless + *follow_symlinks* is ``False``. This method can raise :exc:`OSError`, such as :exc:`PermissionError`, but :exc:`FileNotFoundError` is caught and not raised. - In most cases, no system call is required. - .. method:: is_file(\*, follow_symlinks=True) - If *follow_symlinks* is ``True`` (the default), return ``True`` if the - entry is a file or a symbolic link pointing to a file; return ``False`` - if it is or points to a directory or other non-file entry, or if it - doesn't exist anymore. + Return ``True`` if this entry is a file or a symbolic link pointing to a + file; return ``False`` if the entry is or points to a directory or other + non-file entry, or if it doesn't exist anymore. If *follow_symlinks* is ``False``, return ``True`` only if this entry - is a file; return ``False`` if it is a directory or other non-file entry, + is a file (without following symlinks); return ``False`` if the entry is + a directory or other non-file entry, or if it doesn't exist anymore. + + The result is cached on the ``DirEntry`` object. Caching, system calls + made, and exceptions raised are as per :func:`~DirEntry.is_dir`. + + .. method:: is_symlink() + + Return ``True`` if this entry is a symbolic link (even if broken); + return ``False`` if the entry points to a directory or any kind of file, or if it doesn't exist anymore. - The result is cached on the ``DirEntry`` object. Call :func:`os.stat` - along with :func:`stat.S_ISREG` to fetch up-to-date information. + The result is cached on the ``DirEntry`` object. Call + :func:`os.path.islink` to fetch up-to-date information. + + On the first, uncached call, no system call is required in most cases. + Specifically, neither Windows or Unix require a system call, except on + certain Unix file systems, such as network file systems, that return + ``dirent.d_type == DT_UNKNOWN``. This method can raise :exc:`OSError`, such as :exc:`PermissionError`, but :exc:`FileNotFoundError` is caught and not raised. - In most cases, no system call is required. - - .. method:: is_symlink() - - Return ``True`` if this entry is a symbolic link (even if broken); - return ``False`` if it points to a directory or any kind of file, - or if it doesn't exist anymore. - - The result is cached on the ``DirEntry`` object. Call - :func:`os.path.islink` to fetch up-to-date information. - - The method can raise :exc:`OSError`, such as :exc:`PermissionError`, - but :exc:`FileNotFoundError` is caught and not raised. - - In most cases, no system call is required. - .. method:: stat(\*, follow_symlinks=True) Return a :class:`stat_result` object for this entry. This method follows symbolic links by default; to stat a symbolic link add the ``follow_symlinks=False`` argument. - On Unix, this method always requires a system call. On Windows, - ``DirEntry.stat()`` requires a system call only if the - entry is a symbolic link, and ``DirEntry.stat(follow_symlinks=False)`` - never requires a system call. + On Unix, this method always requires a system call. On Windows, it + only requires a system call if *follow_symlinks* is ``True`` and the + entry is a symbolic link. On Windows, the ``st_ino``, ``st_dev`` and ``st_nlink`` attributes of the :class:`stat_result` are always set to zero. Call :func:`os.stat` to get these attributes. - The result is cached on the ``DirEntry`` object. Call :func:`os.stat` - to fetch up-to-date information. + The result is cached on the ``DirEntry`` object, with a separate cache + for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` to + fetch up-to-date information. Note that there is a nice correspondence between several attributes and methods of ``DirEntry`` and of :class:`pathlib.Path`. In -- Repository URL: https://hg.python.org/cpython