mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-12-18 06:14:00 +08:00
Code Issues Packages Projects Releases Wiki Activity

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
Show Stats 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.
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.
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. Call :func:`os.stat`
along with :func:`stat.S_ISDIR` 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` 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,
or if it doesn't exist anymore.
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. Call :func:`os.stat`
along with :func:`stat.S_ISREG` to fetch up-to-date information.
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.
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 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.
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.
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``.
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)
@ -2023,17 +2026,17 @@ features:
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