Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(38971)

Side by Side Diff: Doc/library/os.rst

Issue 25994: File descriptor leaks in os.scandir()
Patch Set: Created 3 years, 7 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | Doc/whatsnew/3.6.rst » ('j') | Doc/whatsnew/3.6.rst » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`os` --- Miscellaneous operating system interfaces 1 :mod:`os` --- Miscellaneous operating system interfaces
2 ======================================================= 2 =======================================================
3 3
4 .. module:: os 4 .. module:: os
5 :synopsis: Miscellaneous operating system interfaces. 5 :synopsis: Miscellaneous operating system interfaces.
6 6
7 7
8 This module provides a portable way of using operating system dependent 8 This module provides a portable way of using operating system dependent
9 functionality. If you just want to read or write a file see :func:`open`, if 9 functionality. If you just want to read or write a file see :func:`open`, if
10 you want to manipulate paths, see the :mod:`os.path` module, and if you want to 10 you want to manipulate paths, see the :mod:`os.path` module, and if you want to
(...skipping 1872 matching lines...) Expand 10 before | Expand all | Expand 10 after
1883 require a system call for symbolic links; :func:`DirEntry.stat` 1883 require a system call for symbolic links; :func:`DirEntry.stat`
1884 always requires a system call on Unix but only requires one for 1884 always requires a system call on Unix but only requires one for
1885 symbolic links on Windows. 1885 symbolic links on Windows.
1886 1886
1887 On Unix, *path* can be of type :class:`str` or :class:`bytes` (use 1887 On Unix, *path* can be of type :class:`str` or :class:`bytes` (use
1888 :func:`~os.fsencode` and :func:`~os.fsdecode` to encode and decode 1888 :func:`~os.fsencode` and :func:`~os.fsdecode` to encode and decode
1889 :class:`bytes` paths). On Windows, *path* must be of type :class:`str`. 1889 :class:`bytes` paths). On Windows, *path* must be of type :class:`str`.
1890 On both sytems, the type of the :attr:`~DirEntry.name` and 1890 On both sytems, the type of the :attr:`~DirEntry.name` and
1891 :attr:`~DirEntry.path` attributes of each :class:`DirEntry` will be of 1891 :attr:`~DirEntry.path` attributes of each :class:`DirEntry` will be of
1892 the same type as *path*. 1892 the same type as *path*.
1893
1894 The :func:`scandir` iterator supports the :term:`context manager` protocol
1895 and has the following method:
1896
1897 .. method:: scandir.close()
1898
1899 Close the iterator and free acquired resources.
1900
1901 This is called automatically when the iterator is exhausted or garbage
1902 collected, or when an error happened during iterating. However it
Jim.J.Jewett 2016/02/10 23:20:41 happened -> happens
storchaka 2016/02/11 12:20:36 Done.
1903 is advisable to call it explicitly or use the :keyword:`with`
1904 statement.
1905
1906 .. versionadded:: 3.6
1893 1907
1894 The following example shows a simple use of :func:`scandir` to display all 1908 The following example shows a simple use of :func:`scandir` to display all
1895 the files (excluding directories) in the given *path* that don't start with 1909 the files (excluding directories) in the given *path* that don't start with
1896 ``'.'``. The ``entry.is_file()`` call will generally not make an additional 1910 ``'.'``. The ``entry.is_file()`` call will generally not make an additional
1897 system call:: 1911 system call::
1898 1912
1899 for entry in os.scandir(path): 1913 with os.scandir(path) as it:
1900 if not entry.name.startswith('.') and entry.is_file(): 1914 for entry in it:
1901 print(entry.name) 1915 if not entry.name.startswith('.') and entry.is_file():
1916 print(entry.name)
1902 1917
1903 .. note:: 1918 .. note::
1904 1919
1905 On Unix-based systems, :func:`scandir` uses the system's 1920 On Unix-based systems, :func:`scandir` uses the system's
1906 `opendir() <http://pubs.opengroup.org/onlinepubs/009695399/functions/opend ir.html>`_ 1921 `opendir() <http://pubs.opengroup.org/onlinepubs/009695399/functions/opend ir.html>`_
1907 and 1922 and
1908 `readdir() <http://pubs.opengroup.org/onlinepubs/009695399/functions/readd ir_r.html>`_ 1923 `readdir() <http://pubs.opengroup.org/onlinepubs/009695399/functions/readd ir_r.html>`_
1909 functions. On Windows, it uses the Win32 1924 functions. On Windows, it uses the Win32
1910 `FindFirstFileW <http://msdn.microsoft.com/en-us/library/windows/desktop/a a364418(v=vs.85).aspx>`_ 1925 `FindFirstFileW <http://msdn.microsoft.com/en-us/library/windows/desktop/a a364418(v=vs.85).aspx>`_
1911 and 1926 and
1912 `FindNextFileW <http://msdn.microsoft.com/en-us/library/windows/desktop/aa 364428(v=vs.85).aspx>`_ 1927 `FindNextFileW <http://msdn.microsoft.com/en-us/library/windows/desktop/aa 364428(v=vs.85).aspx>`_
1913 functions. 1928 functions.
1914 1929
1915 .. versionadded:: 3.5 1930 .. versionadded:: 3.5
1931
1932 .. versionadded:: 3.6
1933 Added support for the :term:`context manager` protocol and the
1934 :func:`~scandir.close()` method. If a :func:`scandir` iterator is not
Jim.J.Jewett 2016/02/10 23:20:41 "is not ... nor" -> "is neither ... nor"
Martin Panter 2016/02/11 02:22:20 Yes, even better. (This started off as “is not . .
storchaka 2016/02/11 12:20:36 Done.
1935 exhausted nor explicitly closed a :exc:`ResourceWarning` will be emitted
1936 in its destructor.
1916 1937
1917 1938
1918 .. class:: DirEntry 1939 .. class:: DirEntry
1919 1940
1920 Object yielded by :func:`scandir` to expose the file path and other file 1941 Object yielded by :func:`scandir` to expose the file path and other file
1921 attributes of a directory entry. 1942 attributes of a directory entry.
1922 1943
1923 :func:`scandir` will provide as much of this information as possible without 1944 :func:`scandir` will provide as much of this information as possible without
1924 making additional system calls. When a ``stat()`` or ``lstat()`` system call 1945 making additional system calls. When a ``stat()`` or ``lstat()`` system call
1925 is made, the ``DirEntry`` object will cache the result. 1946 is made, the ``DirEntry`` object will cache the result.
(...skipping 1818 matching lines...) Expand 10 before | Expand all | Expand 10 after
3744 :exc:`NotImplementedError` will be raised. 3765 :exc:`NotImplementedError` will be raised.
3745 3766
3746 For an easy-to-use interface to the random number generator 3767 For an easy-to-use interface to the random number generator
3747 provided by your platform, please see :class:`random.SystemRandom`. 3768 provided by your platform, please see :class:`random.SystemRandom`.
3748 3769
3749 .. versionchanged:: 3.5 3770 .. versionchanged:: 3.5
3750 On Linux 3.17 and newer, the ``getrandom()`` syscall is now used 3771 On Linux 3.17 and newer, the ``getrandom()`` syscall is now used
3751 when available. On OpenBSD 5.6 and newer, the C ``getentropy()`` 3772 when available. On OpenBSD 5.6 and newer, the C ``getentropy()``
3752 function is now used. These functions avoid the usage of an internal file 3773 function is now used. These functions avoid the usage of an internal file
3753 descriptor. 3774 descriptor.
OLDNEW
« no previous file with comments | « no previous file | Doc/whatsnew/3.6.rst » ('j') | Doc/whatsnew/3.6.rst » ('J')

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+