Skip to content

C
cpython
Commit 50c40006 authored by Georg Brandl's avatar Georg Brandl
Browse files
Options

"Refactor" docs for the new dir_fd, follow_symlinks, path-as-fd APIs: document... 

"Refactor" docs for the new dir_fd, follow_symlinks, path-as-fd APIs: document the options at a central place and link to it.
parent 6aed5fe5
Hide whitespace changes
Inline Side-by-side
Showing with 151 additions and 269 deletions
Doc/library/os.rst
View file @ 50c40006
...@@ -823,13 +823,8 @@ as internal buffering of data. ...@@ -823,13 +823,8 @@ as internal buffering of data.
this module too (see :ref:`open-constants`). In particular, on Windows adding this module too (see :ref:`open-constants`). In particular, on Windows adding
:const:`O_BINARY` is needed to open files in binary mode. :const:`O_BINARY` is needed to open files in binary mode.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
...@@ -1171,6 +1166,49 @@ Querying the size of a terminal ...@@ -1171,6 +1166,49 @@ Querying the size of a terminal
Files and Directories Files and Directories
--------------------- ---------------------
On some Unix platforms, many of these functions support one or more of these
features:
.. _path_fd:
* For some functions, the *path* argument can be not only a string giving a path
name, but also a file descriptor. The function will then operate on the file
referred to by the descriptor. (For POSIX systems, this will use the ``f...``
versions of the function.)
You can check whether or not *path* can be specified as a file descriptor on
your platform using :data:`os.supports_fd`. If it is unavailable, using it
will raise a :exc:`NotImplementedError`.
If the function also supports *dir_fd* or *follow_symlinks* arguments, it is
an error to specify one of those when supplying *path* as a file descriptor.
.. _dir_fd:
* For functions with a *dir_fd* parameter: If *dir_fd* is not ``None``, it
should be a file descriptor referring to a directory, and the path to operate
on should be relative; path will then be relative to that directory. If the
path is absolute, *dir_fd* is ignored. (For POSIX systems, this will use the
``f...at`` versions of the function.)
You can check whether or not *dir_fd* is supported on your platform using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise a
:exc:`NotImplementedError`.
.. _follow_symlinks:
* For functions ith a *follow_symlinks* parameter: If *follow_symlinks* is
``False``, and the last element of the path to operate on is a symbolic link,
the function will operate on the symbolic link itself instead of the file the
link points to. (For POSIX systems, this will use the ``l...`` versions of
the function.)
You can check whether or not *follow_symlinks* is supported on your platform
using :data:`os.supports_follow_symlinks`. If it is unavailable, using it
will raise a :exc:`NotImplementedError`.
.. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True) .. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)
Use the real uid/gid to test for access to *path*. Note that most operations Use the real uid/gid to test for access to *path*. Note that most operations
...@@ -1182,13 +1220,8 @@ Files and Directories ...@@ -1182,13 +1220,8 @@ Files and Directories
:const:`False` if not. See the Unix man page :manpage:`access(2)` for more :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
information. information.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support specifying :ref:`paths relative to directory
directory, and *path* should be relative; path will then be relative to descriptors <dir_fd>` and :ref:`not following symlinks <follow_symlinks>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *effective_ids* is ``True``, :func:`access` will perform its access If *effective_ids* is ``True``, :func:`access` will perform its access
checks using the effective uid/gid instead of the real uid/gid. checks using the effective uid/gid instead of the real uid/gid.
...@@ -1196,13 +1229,6 @@ Files and Directories ...@@ -1196,13 +1229,6 @@ Files and Directories
or not it is available using :data:`os.supports_effective_ids`. If it is or not it is available using :data:`os.supports_effective_ids`. If it is
unavailable, using it will raise a :exc:`NotImplementedError`. unavailable, using it will raise a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`access` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
.. note:: .. note::
...@@ -1268,24 +1294,21 @@ Files and Directories ...@@ -1268,24 +1294,21 @@ Files and Directories
Change the current working directory to *path*. Change the current working directory to *path*.
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`working on a file descriptor <path_fd>`. The
This functionality may not be supported on your platform; you can check descriptor must refer to an opened directory, not an open file.
whether or not it is available using :data:`os.supports_fd`. If it is
unavailable, using it will raise a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying *path* as a file descriptor Added support for specifying *path* as a file descriptor
on some platforms, and the *dir_fd*, *effective_ids*, and on some platforms.
*follow_symlinks* parameters.
.. function:: fchdir(fd) .. function:: fchdir(fd)
Change the current working directory to the directory represented by the file Change the current working directory to the directory represented by the file
descriptor *fd*. The descriptor must refer to an opened directory, not an open descriptor *fd*. The descriptor must refer to an opened directory, not an
file. Equivalent to ``os.chdir(fd)``. open file. Equivalent to ``os.chdir(fd)``.
Availability: Unix. Availability: Unix.
...@@ -1322,12 +1345,7 @@ Files and Directories ...@@ -1322,12 +1345,7 @@ Files and Directories
* :data:`stat.SF_NOUNLINK` * :data:`stat.SF_NOUNLINK`
* :data:`stat.SF_SNAPSHOT` * :data:`stat.SF_SNAPSHOT`
If *follow_symlinks* is ``False``, and the last element of the path is a This function can support :ref:`not following symlinks <follow_symlinks>`.
symbolic link, :func:`follow_symlinks` will examine the symbolic link itself
instead of the file the link points to. *follow_symlinks* may not be
supported on your platform; you can check whether or not it is available
using :data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
Availability: Unix. Availability: Unix.
...@@ -1367,37 +1385,17 @@ Files and Directories ...@@ -1367,37 +1385,17 @@ Files and Directories
* :data:`stat.S_IWOTH` * :data:`stat.S_IWOTH`
* :data:`stat.S_IXOTH` * :data:`stat.S_IXOTH`
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>`,
This functionality may not be supported on your platform; you can check :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
whether or not it is available using :data:`os.supports_fd`. If it is following symlinks <follow_symlinks>`.
unavailable, using it will raise a :exc:`NotImplementedError`.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a
directory, and *path* should be relative; path will then be relative to
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`chmod` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
It is an error to use *dir_fd* or *follow_symlinks* when specifying
*path* as an open file descriptor.
Availability: Unix, Windows. Availability: Unix, Windows.
.. note:: .. note::
Although Windows supports :func:`chmod`, you can only set the file's read-only Although Windows supports :func:`chmod`, you can only set the file's
flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD`` read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
constants or a corresponding integer value). All other bits are constants or a corresponding integer value). All other bits are ignored.
ignored.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying *path* as an open file descriptor, Added support for specifying *path* as an open file descriptor,
...@@ -1406,31 +1404,12 @@ Files and Directories ...@@ -1406,31 +1404,12 @@ Files and Directories
.. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True) .. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)
Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave Change the owner and group id of *path* to the numeric *uid* and *gid*. To
one of the ids unchanged, set it to -1. leave one of the ids unchanged, set it to -1.
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>`,
This functionality may not be supported on your platform; you can check :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
whether or not it is available using :data:`os.supports_fd`. If it is following symlinks <follow_symlinks>`.
unavailable, using it will raise a :exc:`NotImplementedError`.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a
directory, and *path* should be relative; path will then be relative to
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`chown` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
It is an error to use *dir_fd* or *follow_symlinks* when specifying
*path* as an open file descriptor.
See :func:`shutil.chown` for a higher-level function that accepts names in See :func:`shutil.chown` for a higher-level function that accepts names in
addition to numeric ids. addition to numeric ids.
...@@ -1448,23 +1427,19 @@ Files and Directories ...@@ -1448,23 +1427,19 @@ Files and Directories
*path*. *attribute* can be bytes or str. If it is str, it is encoded *path*. *attribute* can be bytes or str. If it is str, it is encoded
with the filesystem encoding. with the filesystem encoding.
*path* may be specified as either a string or an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
If *follow_symlinks* is ``False``, and the last element of the path is a Availability: Linux.
symbolic link, :func:`setxattr` will examine the symbolic link itself
instead of the file the link points to. It is an error to use
*follow_symlinks* when specifying *path* as an open file descriptor.
Availability: Linux
.. versionadded:: 3.3 .. versionadded:: 3.3
.. function:: lchflags(path, flags) .. function:: lchflags(path, flags)
Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do
follow symbolic links. not follow symbolic links. Equivalent to ``os.chflags(path, flags,
Equivalent to ``os.chflags(path, flags, follow_symlinks=False)``. follow_symlinks=False)``.
Availability: Unix. Availability: Unix.
...@@ -1472,18 +1447,18 @@ Files and Directories ...@@ -1472,18 +1447,18 @@ Files and Directories
.. function:: lchmod(path, mode) .. function:: lchmod(path, mode)
Change the mode of *path* to the numeric *mode*. If path is a symlink, this Change the mode of *path* to the numeric *mode*. If path is a symlink, this
affects the symlink rather than the target. See the docs for :func:`chmod` affects the symlink rather than the target. See the docs for :func:`chmod`
for possible values of *mode*. for possible values of *mode*. Equivalent to ``os.chmod(path, mode,
Equivalent to ``os.chmod(path, mode, follow_symlinks=False)``. follow_symlinks=False)``.
Availability: Unix. Availability: Unix.
.. function:: lchown(path, uid, gid) .. function:: lchown(path, uid, gid)
Change the owner and group id of *path* to the numeric *uid* and *gid*. This Change the owner and group id of *path* to the numeric *uid* and *gid*. This
function will not follow symbolic links. function will not follow symbolic links. Equivalent to ``os.chown(path, uid,
Equivalent to ``os.chown(path, uid, gid, follow_symlinks=False)``. gid, follow_symlinks=False)``.
Availability: Unix. Availability: Unix.
...@@ -1492,21 +1467,17 @@ Files and Directories ...@@ -1492,21 +1467,17 @@ Files and Directories
Create a hard link pointing to *src* named *dst*. Create a hard link pointing to *src* named *dst*.
If either *src_dir_fd* or *dst_dir_fd* is not ``None``, it should be a If either *src_dir_fd* or *dst_dir_fd* is not ``None``, it should be a file
file descriptor referring to a directory, and the corresponding path descriptor referring to a directory, and the corresponding path (*src* or
(*src* or *dst*) should be relative; that path will then be relative to *dst*) should be relative; that path will then be relative to that directory.
that directory. (If *src* is absolute, *src_dir_fd* is ignored; the same (If *src* is absolute, *src_dir_fd* is ignored; the same goes for *dst* and
goes for *dst* and *dst_dir_fd*.) *dst_dir_fd*.) *src_dir_fd* and *dst_dir_fd* may not be supported on your
*src_dir_fd* and *dst_dir_fd* may not be supported on your platform; platform; you can check whether or not they are available using
you can check whether or not they are available using :data:`os.supports_dir_fd`. :data:`os.supports_dir_fd`. If they are unavailable, using either will raise
If they are unavailable, using either will raise a :exc:`NotImplementedError`. a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of *src* is a This function can also support :ref:`not following symlinks
symbolic link, :func:`link` will use the symbolic link itself instead <follow_symlinks>`.
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
...@@ -1520,16 +1491,15 @@ Files and Directories ...@@ -1520,16 +1491,15 @@ Files and Directories
.. function:: listdir(path='.') .. function:: listdir(path='.')
Return a list containing the names of the entries in the directory given by Return a list containing the names of the entries in the directory given by
*path* (default: ``'.'``). The list is in arbitrary order. It does not include the special *path* (default: ``'.'``). The list is in arbitrary order. It does not
entries ``'.'`` and ``'..'`` even if they are present in the directory. include the special entries ``'.'`` and ``'..'`` even if they are present in
the directory.
This function can be called with a bytes or string argument, and returns This function can be called with a bytes or string argument, and returns
filenames of the same datatype. filenames of the same datatype.
On some platforms, *path* may also be specified as an open file descriptor. This function can also support :ref:`specifying an open file descriptor
This functionality may not be supported on your platform; you can check <path_fd>` (referring to a directory).
whether or not it is available using :data:`os.supports_fd`. If it is
unavailable, using it will raise a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
...@@ -1539,22 +1509,18 @@ Files and Directories ...@@ -1539,22 +1509,18 @@ Files and Directories
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*. Added support for specifying an open file descriptor for *path*.
.. function:: listxattr(path=None, *, follow_symlinks=True)
Return a list of the extended filesystem attributes on *path*. .. function:: listxattr(path=None, *, follow_symlinks=True)
The attributes in the list are represented as strings decoded
with the filesystem encoding.
*path* may be specified as either ``None``, a string, or an open file Return a list of the extended filesystem attributes on *path*. The
descriptor. If *path* is ``None``, :func:`listxattr` will examine the attributes in the list are represented as strings decoded with the filesystem
current directory. encoding. If *path* is ``None``, :func:`listxattr` will examine the current
directory.
If *follow_symlinks* is ``False``, and the last element of the path is a This function can support :ref:`specifying a file descriptor <path_fd>` and
symbolic link, :func:`listxattr` will examine the symbolic link itself :ref:`not following symlinks <follow_symlinks>`.
instead of the file the link points to. It is an error to use
*follow_symlinks* when specifying *path* as an open file descriptor.
Availability: Linux Availability: Linux.
.. versionadded:: 3.3 .. versionadded:: 3.3
...@@ -1566,13 +1532,8 @@ Files and Directories ...@@ -1566,13 +1532,8 @@ Files and Directories
platforms that do not support symbolic links, this is an alias for platforms that do not support symbolic links, this is an alias for
:func:`~os.stat`. (Equivalent to ``os.stat(path, follow_symlinks=False)``.) :func:`~os.stat`. (Equivalent to ``os.stat(path, follow_symlinks=False)``.)
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
.. versionchanged:: 3.2 .. versionchanged:: 3.2
Added support for Windows 6.0 (Vista) symbolic links. Added support for Windows 6.0 (Vista) symbolic links.
...@@ -1586,13 +1547,8 @@ Files and Directories ...@@ -1586,13 +1547,8 @@ Files and Directories
Create a FIFO (a named pipe) named *path* with numeric mode *mode*. Create a FIFO (a named pipe) named *path* with numeric mode *mode*.
The current umask value is first masked out from the mode. The current umask value is first masked out from the mode.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
FIFOs are pipes that can be accessed like regular files. FIFOs exist until they FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
...@@ -1616,13 +1572,8 @@ Files and Directories ...@@ -1616,13 +1572,8 @@ Files and Directories
*device* defines the newly created device special file (probably using *device* defines the newly created device special file (probably using
:func:`os.makedev`), otherwise it is ignored. :func:`os.makedev`), otherwise it is ignored.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
.. versionadded:: 3.3 .. versionadded:: 3.3
The *dir_fd* argument. The *dir_fd* argument.
...@@ -1649,17 +1600,12 @@ Files and Directories ...@@ -1649,17 +1600,12 @@ Files and Directories
Create a directory named *path* with numeric mode *mode*. Create a directory named *path* with numeric mode *mode*.
On some systems, *mode* is ignored. Where it is used, the current On some systems, *mode* is ignored. Where it is used, the current umask
umask value is first masked out. If the directory already value is first masked out. If the directory already exists, :exc:`OSError`
exists, :exc:`OSError` is raised. is raised.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
It is also possible to create temporary directories; see the It is also possible to create temporary directories; see the
:mod:`tempfile` module's :func:`tempfile.mkdtemp` function. :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
...@@ -1725,21 +1671,16 @@ Files and Directories ...@@ -1725,21 +1671,16 @@ Files and Directories
.. function:: readlink(path, *, dir_fd=None) .. function:: readlink(path, *, dir_fd=None)
Return a string representing the path to which the symbolic link points. The Return a string representing the path to which the symbolic link points. The
result may be either an absolute or relative pathname; if it is relative, it may result may be either an absolute or relative pathname; if it is relative, it
be converted to an absolute pathname using ``os.path.join(os.path.dirname(path), may be converted to an absolute pathname using
result)``. ``os.path.join(os.path.dirname(path), result)``.
If the *path* is a string object, the result will also be a string object, If the *path* is a string object, the result will also be a string object,
and the call may raise an UnicodeDecodeError. If the *path* is a bytes and the call may raise an UnicodeDecodeError. If the *path* is a bytes
object, the result will be a bytes object. object, the result will be a bytes object.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
Availability: Unix, Windows Availability: Unix, Windows
...@@ -1752,16 +1693,11 @@ Files and Directories ...@@ -1752,16 +1693,11 @@ Files and Directories
.. function:: remove(path, *, dir_fd=None) .. function:: remove(path, *, dir_fd=None)
Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is
is raised. Use :func:`rmdir` to remove directories. raised. Use :func:`rmdir` to remove directories.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
On Windows, attempting to remove a file that is in use causes an exception to On Windows, attempting to remove a file that is in use causes an exception to
be raised; on Unix, the directory entry is removed but the storage allocated be raised; on Unix, the directory entry is removed but the storage allocated
...@@ -1795,15 +1731,10 @@ Files and Directories ...@@ -1795,15 +1731,10 @@ Files and Directories
*attribute* should be bytes or str. If it is a string, it is encoded *attribute* should be bytes or str. If it is a string, it is encoded
with the filesystem encoding. with the filesystem encoding.
*path* may be specified as either a string or an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`removexattr` will remove the attribute from the
symbolic link itself instead of the file the link points to. It is an
error to use *follow_symlinks* when specifying *path* as an open file
descriptor.
Availability: Linux Availability: Linux.
.. versionadded:: 3.3 .. versionadded:: 3.3
...@@ -1876,13 +1807,8 @@ Files and Directories ...@@ -1876,13 +1807,8 @@ Files and Directories
empty, otherwise, :exc:`OSError` is raised. In order to remove whole empty, otherwise, :exc:`OSError` is raised. In order to remove whole
directory trees, :func:`shutil.rmtree` can be used. directory trees, :func:`shutil.rmtree` can be used.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
...@@ -1918,14 +1844,10 @@ Files and Directories ...@@ -1918,14 +1844,10 @@ Files and Directories
If :data:`XATTR_CREATE` is given and the attribute already exists, the If :data:`XATTR_CREATE` is given and the attribute already exists, the
attribute will not be created and ``ENODATA`` will be raised. attribute will not be created and ``ENODATA`` will be raised.
*path* may be specified as either a string or an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`setxattr` will examine the symbolic link itself
instead of the file the link points to. It is an error to use
*follow_symlinks* when specifying *path* as an open file descriptor.
Availability: Linux Availability: Linux.
.. note:: .. note::
...@@ -2002,30 +1924,17 @@ Files and Directories ...@@ -2002,30 +1924,17 @@ Files and Directories
If you need the exact timestamps you should always use If you need the exact timestamps you should always use
:attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`. :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`.
For backward compatibility, the return value of :func:`~os.stat` is also accessible For backward compatibility, the return value of :func:`~os.stat` is also
as a tuple of at least 10 integers giving the most important (and portable) accessible as a tuple of at least 10 integers giving the most important (and
members of the :c:type:`stat` structure, in the order :attr:`st_mode`, portable) members of the :c:type:`stat` structure, in the order
:attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`, :attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`,
:attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`, :attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`,
:attr:`st_ctime`. More items may be added at the end by some implementations. :attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by
some implementations.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a
directory, and *path* should be relative; path will then be relative to
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`stat` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
It is an error to use *dir_fd* or *follow_symlinks* when specifying This function can support :ref:`specifying an open file descriptor
*path* as an open file descriptor. <path_fd>`, :ref:`specifying a file descriptor <path_fd>` and :ref:`not
following symlinks <follow_symlinks>`.
.. index:: module: stat .. index:: module: stat
...@@ -2094,10 +2003,7 @@ Files and Directories ...@@ -2094,10 +2003,7 @@ Files and Directories
read-only, and if :const:`ST_NOSUID` is set, the semantics of read-only, and if :const:`ST_NOSUID` is set, the semantics of
setuid/setgid bits are disabled or not supported. setuid/setgid bits are disabled or not supported.
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>`.
This functionality may not be supported on your platform; you can check
whether or not it is available using :data:`os.supports_fd`. If it is
unavailable, using it will raise a :exc:`NotImplementedError`.
.. versionchanged:: 3.2 .. versionchanged:: 3.2
The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added. The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
...@@ -2132,17 +2038,17 @@ Files and Directories ...@@ -2132,17 +2038,17 @@ Files and Directories
.. data:: supports_effective_ids .. data:: supports_effective_ids
An object implementing collections.Set indicating which functions in the An object implementing collections.Set indicating which functions in the
:mod:`os` permit use of the *effective_id* parameter for :func:`os.access`. :mod:`os` permit use of the *effective_ids* parameter for :func:`os.access`.
If the local platform supports it, the collection will contain If the local platform supports it, the collection will contain
:func:`os.access`, otherwise it will be empty. :func:`os.access`, otherwise it will be empty.
To check whether you can use the *effective_id* parameter for To check whether you can use the *effective_ids* parameter for
:func:`os.access`, use the ``in`` operator on ``supports_dir_fd``, like so:: :func:`os.access`, use the ``in`` operator on ``supports_dir_fd``, like so::
os.access in os.supports_effective_ids os.access in os.supports_effective_ids
Currently *effective_id* only works on UNIX platforms; Currently *effective_ids* only works on Unix platforms; it does not work on
it does not work on Windows. Windows.
.. versionadded:: 3.3 .. versionadded:: 3.3
...@@ -2196,13 +2102,8 @@ Files and Directories ...@@ -2196,13 +2102,8 @@ Files and Directories
Symbolic link support was introduced in Windows 6.0 (Vista). :func:`symlink` Symbolic link support was introduced in Windows 6.0 (Vista). :func:`symlink`
will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0. will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
.. note:: .. note::
...@@ -2247,7 +2148,7 @@ Files and Directories ...@@ -2247,7 +2148,7 @@ Files and Directories
.. function:: unlink(path, *, dir_fd=None) .. function:: unlink(path, *, dir_fd=None)
Remove (delete) the file *path*. This function is identical to Remove (delete) the file *path*. This function is identical to
:func:`remove`; the :func:`unlink` name is its traditional Unix :func:`remove`; the ``unlink`` name is its traditional Unix
name. Please see the documentation for :func:`remove` for name. Please see the documentation for :func:`remove` for
further information. further information.
...@@ -2287,28 +2188,9 @@ Files and Directories ...@@ -2287,28 +2188,9 @@ Files and Directories
use the *st_atime_ns* and *st_mtime_ns* fields from the :func:`os.stat` use the *st_atime_ns* and *st_mtime_ns* fields from the :func:`os.stat`
result object with the *ns* parameter to `utime`. result object with the *ns* parameter to `utime`.
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>`,
This functionality may not be supported on your platform; you can check :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
whether or not it is available using :data:`os.supports_fd`. If it is following symlinks <follow_symlinks>`.
unavailable, using it will raise a :exc:`NotImplementedError`.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a
directory, and *path* should be relative; path will then be relative to
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`utime` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
It is an error to use *dir_fd* or *follow_symlinks* when specifying
*path* as an open file descriptor.
Availability: Unix, Windows. Availability: Unix, Windows.
...@@ -2362,9 +2244,9 @@ Files and Directories ...@@ -2362,9 +2244,9 @@ Files and Directories
.. note:: .. note::
Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a Be aware that setting *followlinks* to ``True`` can lead to infinite
link points to a parent directory of itself. :func:`walk` does not keep track of recursion if a link points to a parent directory of itself. :func:`walk`
the directories it visited already. does not keep track of the directories it visited already.
.. note:: .. note::
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7