mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Enhance os.scandir() doc

Browse source 
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.
This commit is contained in:
Victor Stinner 2016-01-31 18:36:41 +01:00
parent fe5f614418
commit 5f0c5d92ef
1 changed files with 38 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

73
Doc/library/os.rst
View file

@ -1960,62 +1960,65 @@ features:
Return the inode number of the entry. 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. 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) .. method:: is_dir(\*, follow_symlinks=True)
If *follow_symlinks* is ``True`` (the default), return ``True`` if the Return ``True`` if this entry is a directory or a symbolic link pointing
entry is a directory or a symbolic link pointing to a directory; to a directory; return ``False`` if the entry is or points to any other
return ``False`` if it is or points to any other kind of file, or if it kind of file, or if it doesn't exist anymore.
doesn't exist anymore.
If *follow_symlinks* is ``False``, return ``True`` only if this entry If *follow_symlinks* is ``False``, return ``True`` only if this entry
is a directory; return ``False`` if it is any other kind of file is a directory (without following symlinks); return ``False`` if the
or if it doesn't exist anymore. entry 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` The result is cached on the ``DirEntry`` object, with a separate cache
along with :func:`stat.S_ISDIR` to fetch up-to-date information. 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`, This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
but :exc:`FileNotFoundError` is caught and not raised. but :exc:`FileNotFoundError` is caught and not raised.
In most cases, no system call is required.
.. method:: is_file(\*, follow_symlinks=True) .. method:: is_file(\*, follow_symlinks=True)
If *follow_symlinks* is ``True`` (the default), return ``True`` if the Return ``True`` if this entry is a file or a symbolic link pointing to a
entry is a file or a symbolic link pointing to a file; return ``False`` file; return ``False`` if the entry is or points to a directory or other
if it is or points to a directory or other non-file entry, or if it non-file entry, or if it doesn't exist anymore.
doesn't exist anymore.
If *follow_symlinks* is ``False``, return ``True`` only if this entry 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
or if it doesn't exist anymore. a directory or other non-file entry, or if it doesn't exist anymore.
The result is cached on the ``DirEntry`` object. Call :func:`os.stat` The result is cached on the ``DirEntry`` object. Caching, system calls
along with :func:`stat.S_ISREG` to fetch up-to-date information. made, and exceptions raised are as per :func:`~DirEntry.is_dir`.
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() .. method:: is_symlink()
Return ``True`` if this entry is a symbolic link (even if broken); 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, return ``False`` if the entry points to a directory or any kind of file,
or if it doesn't exist anymore. or if it doesn't exist anymore.
The result is cached on the ``DirEntry`` object. Call The result is cached on the ``DirEntry`` object. Call
:func:`os.path.islink` to fetch up-to-date information. :func:`os.path.islink` to fetch up-to-date information.
The method can raise :exc:`OSError`, such as :exc:`PermissionError`, On the first, uncached call, no system call is required in most cases.
but :exc:`FileNotFoundError` is caught and not raised. 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``.
In most cases, no system call is required. This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
but :exc:`FileNotFoundError` is caught and not raised.
.. method:: stat(\*, follow_symlinks=True) .. method:: stat(\*, follow_symlinks=True)
@ -2023,17 +2026,17 @@ features:
follows symbolic links by default; to stat a symbolic link add the follows symbolic links by default; to stat a symbolic link add the
``follow_symlinks=False`` argument. ``follow_symlinks=False`` argument.
On Unix, this method always requires a system call. On Windows, On Unix, this method always requires a system call. On Windows, it
``DirEntry.stat()`` requires a system call only if the only requires a system call if *follow_symlinks* is ``True`` and the
entry is a symbolic link, and ``DirEntry.stat(follow_symlinks=False)`` entry is a symbolic link.
never requires a system call.
On Windows, the ``st_ino``, ``st_dev`` and ``st_nlink`` attributes of the 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 :class:`stat_result` are always set to zero. Call :func:`os.stat` to
get these attributes. get these attributes.
The result is cached on the ``DirEntry`` object. Call :func:`os.stat` The result is cached on the ``DirEntry`` object, with a separate cache
to fetch up-to-date information. 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 Note that there is a nice correspondence between several attributes
and methods of ``DirEntry`` and of :class:`pathlib.Path`. In and methods of ``DirEntry`` and of :class:`pathlib.Path`. In