[Python-checkins] cpython: Issue #27038: Expose DirEntry as os.DirEntry.
brett.cannon
python-checkins at python.org
Fri Jun 24 17:14:51 EDT 2016
https://hg.python.org/cpython/rev/b841972ed0bd
changeset: 102164:b841972ed0bd
user: Brett Cannon <brett at python.org>
date: Fri Jun 24 14:14:44 2016 -0700
summary:
Issue #27038: Expose DirEntry as os.DirEntry.
Thanks to Jelle Zijlstra for the code portion of the patch.
files:
Doc/library/os.rst | 56 ++++++++++++++++--------------
Lib/test/test_os.py | 1 +
Misc/NEWS | 3 +
Modules/posixmodule.c | 1 +
4 files changed, 34 insertions(+), 27 deletions(-)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1920,25 +1920,26 @@
.. function:: scandir(path='.')
- Return an iterator of :class:`DirEntry` objects corresponding to the entries
- in the directory given by *path*. The entries are yielded in arbitrary
- order, and the special entries ``'.'`` and ``'..'`` are not included.
+ Return an iterator of :class:`os.DirEntry` objects corresponding to the
+ entries in the directory given by *path*. The entries are yielded in
+ arbitrary order, and the special entries ``'.'`` and ``'..'`` are not
+ included.
Using :func:`scandir` instead of :func:`listdir` can significantly
increase the performance of code that also needs file type or file
- attribute information, because :class:`DirEntry` objects expose this
+ attribute information, because :class:`os.DirEntry` objects expose this
information if the operating system provides it when scanning a directory.
- All :class:`DirEntry` methods may perform a system call, but
- :func:`~DirEntry.is_dir` and :func:`~DirEntry.is_file` usually only
- require a system call for symbolic links; :func:`DirEntry.stat`
+ All :class:`os.DirEntry` methods may perform a system call, but
+ :func:`~os.DirEntry.is_dir` and :func:`~os.DirEntry.is_file` usually only
+ require a system call for symbolic links; :func:`os.DirEntry.stat`
always requires a system call on Unix but only requires one for
symbolic links on Windows.
On Unix, *path* can be of type :class:`str` or :class:`bytes` (use
:func:`~os.fsencode` and :func:`~os.fsdecode` to encode and decode
:class:`bytes` paths). On Windows, *path* must be of type :class:`str`.
- On both sytems, the type of the :attr:`~DirEntry.name` and
- :attr:`~DirEntry.path` attributes of each :class:`DirEntry` will be of
+ On both sytems, the type of the :attr:`~os.DirEntry.name` and
+ :attr:`~os.DirEntry.path` attributes of each :class:`os.DirEntry` will be of
the same type as *path*.
The :func:`scandir` iterator supports the :term:`context manager` protocol
@@ -1993,22 +1994,22 @@
:func:`scandir` will provide as much of this information as possible without
making additional system calls. When a ``stat()`` or ``lstat()`` system call
- is made, the ``DirEntry`` object will cache the result.
-
- ``DirEntry`` instances are not intended to be stored in long-lived data
+ is made, the ``os.DirEntry`` object will cache the result.
+
+ ``os.DirEntry`` instances are not intended to be stored in long-lived data
structures; if you know the file metadata has changed or if a long time has
elapsed since calling :func:`scandir`, call ``os.stat(entry.path)`` to fetch
up-to-date information.
- Because the ``DirEntry`` methods can make operating system calls, they may
+ Because the ``os.DirEntry`` methods can make operating system calls, they may
also raise :exc:`OSError`. If you need very fine-grained
control over errors, you can catch :exc:`OSError` when calling one of the
- ``DirEntry`` methods and handle as appropriate.
-
- To be directly usable as a :term:`path-like object`, ``DirEntry`` implements
- the :class:`os.PathLike` interface.
-
- Attributes and methods on a ``DirEntry`` instance are as follows:
+ ``os.DirEntry`` methods and handle as appropriate.
+
+ To be directly usable as a :term:`path-like object`, ``os.DirEntry``
+ implements the :class:`os.PathLike` interface.
+
+ Attributes and methods on a ``os.DirEntry`` instance are as follows:
.. attribute:: name
@@ -2034,8 +2035,9 @@
Return the inode number of the entry.
- The result is cached on the ``DirEntry`` object. Use ``os.stat(entry.path,
- follow_symlinks=False).st_ino`` to fetch up-to-date information.
+ The result is cached on the ``os.DirEntry`` object. Use
+ ``os.stat(entry.path, follow_symlinks=False).st_ino`` to fetch up-to-date
+ information.
On the first, uncached call, a system call is required on Windows but
not on Unix.
@@ -2050,7 +2052,7 @@
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
+ The result is cached on the ``os.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.
@@ -2074,8 +2076,8 @@
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`.
+ The result is cached on the ``os.DirEntry`` object. Caching, system calls
+ made, and exceptions raised are as per :func:`~os.DirEntry.is_dir`.
.. method:: is_symlink()
@@ -2083,7 +2085,7 @@
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
+ The result is cached on the ``os.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.
@@ -2108,12 +2110,12 @@
:class:`stat_result` are always set to zero. Call :func:`os.stat` to
get these attributes.
- The result is cached on the ``DirEntry`` object, with a separate cache
+ The result is cached on the ``os.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
+ and methods of ``os.DirEntry`` and of :class:`pathlib.Path`. In
particular, the ``name`` attribute has the same
meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()``
and ``stat()`` methods.
diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py
--- a/Lib/test/test_os.py
+++ b/Lib/test/test_os.py
@@ -2854,6 +2854,7 @@
self.assertEqual(stat1, stat2)
def check_entry(self, entry, name, is_dir, is_file, is_symlink):
+ self.assertIsInstance(entry, os.DirEntry)
self.assertEqual(entry.name, name)
self.assertEqual(entry.path, os.path.join(self.path, name))
self.assertEqual(entry.inode(),
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -10,6 +10,9 @@
Library
-------
+- Issue #27038: Expose the DirEntry type as os.DirEntry. Code patch by
+ Jelle Zijlstra.
+
- Issue #27186: Update os.fspath()/PyOS_FSPath() to check the return value of
__fspath__() to be either str or bytes.
diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -13320,6 +13320,7 @@
Py_DECREF(unicode);
}
PyModule_AddObject(m, "_have_functions", list);
+ PyModule_AddObject(m, "DirEntry", (PyObject *)&DirEntryType);
initialized = 1;
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list