diff options
Diffstat (limited to 'Doc/library/os.rst')
| -rw-r--r-- | Doc/library/os.rst | 134 |
1 files changed, 103 insertions, 31 deletions
diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 4265bc2..9456733 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -171,23 +171,60 @@ process and user. .. function:: fsencode(filename) - Encode *filename* to the filesystem encoding with ``'surrogateescape'`` - error handler, or ``'strict'`` on Windows; return :class:`bytes` unchanged. + Encode :term:`path-like <path-like object>` *filename* to the filesystem + encoding with ``'surrogateescape'`` error handler, or ``'strict'`` on + Windows; return :class:`bytes` unchanged. :func:`fsdecode` is the reverse function. .. versionadded:: 3.2 + .. versionchanged:: 3.6 + Support added to accept objects implementing the :class:`os.PathLike` + interface. + .. function:: fsdecode(filename) - Decode *filename* from the filesystem encoding with ``'surrogateescape'`` - error handler, or ``'strict'`` on Windows; return :class:`str` unchanged. + Decode the :term:`path-like <path-like object>` *filename* from the + filesystem encoding with ``'surrogateescape'`` error handler, or ``'strict'`` + on Windows; return :class:`str` unchanged. :func:`fsencode` is the reverse function. .. versionadded:: 3.2 + .. versionchanged:: 3.6 + Support added to accept objects implementing the :class:`os.PathLike` + interface. + + +.. function:: fspath(path) + + Return the file system representation of the path. + + If :class:`str` or :class:`bytes` is passed in, it is returned unchanged. + Otherwise :meth:`~os.PathLike.__fspath__` is called and its value is + returned as long as it is a :class:`str` or :class:`bytes` object. + In all other cases, :exc:`TypeError` is raised. + + .. versionadded:: 3.6 + + +.. class:: PathLike + + An :term:`abstract base class` for objects representing a file system path, + e.g. :class:`pathlib.PurePath`. + + .. versionadded:: 3.6 + + .. abstractmethod:: __fspath__() + + Return the file system path representation of the object. + + The method should only return a :class:`str` or :class:`bytes` object, + with the preference being for :class:`str`. + .. function:: getenv(key, default=None) @@ -1883,35 +1920,51 @@ features: .. 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 systems, the type of the :attr:`~DirEntry.name` and - :attr:`~DirEntry.path` attributes of each :class:`DirEntry` will be of + On both systems, 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 + and has the following method: + + .. method:: scandir.close() + + Close the iterator and free acquired resources. + + This is called automatically when the iterator is exhausted or garbage + collected, or when an error happens during iterating. However it + is advisable to call it explicitly or use the :keyword:`with` + statement. + + .. versionadded:: 3.6 + The following example shows a simple use of :func:`scandir` to display all the files (excluding directories) in the given *path* that don't start with ``'.'``. The ``entry.is_file()`` call will generally not make an additional system call:: - for entry in os.scandir(path): - if not entry.name.startswith('.') and entry.is_file(): - print(entry.name) + with os.scandir(path) as it: + for entry in it: + if not entry.name.startswith('.') and entry.is_file(): + print(entry.name) .. note:: @@ -1927,6 +1980,12 @@ features: .. versionadded:: 3.5 + .. versionadded:: 3.6 + Added support for the :term:`context manager` protocol and the + :func:`~scandir.close()` method. If a :func:`scandir` iterator is neither + exhausted nor explicitly closed a :exc:`ResourceWarning` will be emitted + in its destructor. + .. class:: DirEntry @@ -1935,19 +1994,22 @@ features: :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. + is made, the ``os.DirEntry`` object will cache the result. - ``DirEntry`` instances are not intended to be stored in long-lived data + ``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. + ``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 ``DirEntry`` instance are as follows: + Attributes and methods on a ``os.DirEntry`` instance are as follows: .. attribute:: name @@ -1973,8 +2035,9 @@ features: 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. @@ -1989,7 +2052,7 @@ features: 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. @@ -2013,8 +2076,8 @@ features: 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() @@ -2022,7 +2085,7 @@ features: 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. @@ -2047,17 +2110,21 @@ features: :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 - particular, the ``name`` attribute has the same meaning, as do the - ``is_dir()``, ``is_file()``, ``is_symlink()`` and ``stat()`` methods. + 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. .. versionadded:: 3.5 + .. versionchanged:: 3.6 + Added support for the :class:`os.PathLike` interface. + .. function:: stat(path, \*, dir_fd=None, follow_symlinks=True) @@ -3618,6 +3685,11 @@ Miscellaneous System Information Return the number of CPUs in the system. Returns None if undetermined. + This number is not equivalent to the number of CPUs the current process can + use. The number of usable CPUs can be obtained with + ``len(os.sched_getaffinity(0))`` + + .. versionadded:: 3.4 |