[Python-checkins] cpython (3.5): Enhance os.scandir() doc
victor.stinner
python-checkins at python.org
Sun Jan 31 12:37:41 EST 2016
https://hg.python.org/cpython/rev/f2c68cb17e31
changeset: 100130:f2c68cb17e31
branch: 3.5
parent: 100127:9a31895a1c9d
user: Victor Stinner <victor.stinner at 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
More information about the Python-checkins
mailing list