Commit e152169d authored by Cheryl Sabella's avatar Cheryl Sabella Committed by larryhastings

bpo-16024: Doc cleanup regarding path_fd, dir_fd, follow_symlinks (GH-5505)

parent 29500737
...@@ -1453,16 +1453,19 @@ features: ...@@ -1453,16 +1453,19 @@ features:
.. _path_fd: .. _path_fd:
* **specifying a file descriptor:** * **specifying a file descriptor:**
For some functions, the *path* argument can be not only a string giving a path Normally the *path* argument provided to functions in the :mod:`os` module
name, but also a file descriptor. The function will then operate on the file must be a string specifying a file path. However, some functions now
referred to by the descriptor. (For POSIX systems, Python will call the alternatively accept an open file descriptor for their *path* argument.
``f...`` version of the function.) The function will then operate on the file referred to by the descriptor.
(For POSIX systems, Python will call the variant of the function prefixed
You can check whether or not *path* can be specified as a file descriptor on with ``f`` (e.g. call ``fchdir`` instead of ``chdir``).)
your platform using :data:`os.supports_fd`. If it is unavailable, using it
will raise a :exc:`NotImplementedError`. You can check whether or not *path* can be specified as a file descriptor
for a particular function on your platform using :data:`os.supports_fd`.
If this functionality is unavailable, using it will raise a
:exc:`NotImplementedError`.
If the function also supports *dir_fd* or *follow_symlinks* arguments, it is If the function also supports *dir_fd* or *follow_symlinks* arguments, it's
an error to specify one of those when supplying *path* as a file descriptor. an error to specify one of those when supplying *path* as a file descriptor.
.. _dir_fd: .. _dir_fd:
...@@ -1471,23 +1474,24 @@ features: ...@@ -1471,23 +1474,24 @@ features:
should be a file descriptor referring to a directory, and the path to operate 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 on should be relative; path will then be relative to that directory. If the
path is absolute, *dir_fd* is ignored. (For POSIX systems, Python will call path is absolute, *dir_fd* is ignored. (For POSIX systems, Python will call
the ``...at`` or ``f...at`` version of the function.) the variant of the function with an ``at`` suffix and possibly prefixed with
``f`` (e.g. call ``faccessat`` instead of ``access``).
You can check whether or not *dir_fd* is supported on your platform using You can check whether or not *dir_fd* is supported for a particular function
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise a on your platform using :data:`os.supports_dir_fd`. If it's unavailable,
:exc:`NotImplementedError`. using it will raise a :exc:`NotImplementedError`.
.. _follow_symlinks: .. _follow_symlinks:
* **not following symlinks:** If *follow_symlinks* is * **not following symlinks:** If *follow_symlinks* is
``False``, and the last element of the path to operate on is a symbolic link, ``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 the function will operate on the symbolic link itself rather than the file
link points to. (For POSIX systems, Python will call the ``l...`` version of pointed to by the link. (For POSIX systems, Python will call the ``l...``
the function.) variant of the function.)
You can check whether or not *follow_symlinks* is supported on your platform You can check whether or not *follow_symlinks* is supported for a particular
using :data:`os.supports_follow_symlinks`. If it is unavailable, using it function on your platform using :data:`os.supports_follow_symlinks`.
will raise a :exc:`NotImplementedError`. If it's unavailable, using it will raise a :exc:`NotImplementedError`.
...@@ -1662,7 +1666,7 @@ features: ...@@ -1662,7 +1666,7 @@ features:
.. availability:: Unix. .. availability:: Unix.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*, Added support for specifying *path* as an open file descriptor,
and the *dir_fd* and *follow_symlinks* arguments. and the *dir_fd* and *follow_symlinks* arguments.
.. versionchanged:: 3.6 .. versionchanged:: 3.6
...@@ -1781,7 +1785,7 @@ features: ...@@ -1781,7 +1785,7 @@ features:
The *path* parameter became optional. The *path* parameter became optional.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*. Added support for specifying *path* as an open file descriptor.
.. versionchanged:: 3.6 .. versionchanged:: 3.6
Accepts a :term:`path-like object`. Accepts a :term:`path-like object`.
...@@ -2593,7 +2597,7 @@ features: ...@@ -2593,7 +2597,7 @@ features:
The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added. The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*. Added support for specifying *path* as an open file descriptor.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`, The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`,
...@@ -2610,59 +2614,61 @@ features: ...@@ -2610,59 +2614,61 @@ features:
.. data:: supports_dir_fd .. data:: supports_dir_fd
A :class:`~collections.abc.Set` object indicating which functions in the A :class:`set` object indicating which functions in the :mod:`os`
:mod:`os` module permit use of their *dir_fd* parameter. Different platforms module accept an open file descriptor for their *dir_fd* parameter.
provide different functionality, and an option that might work on one might Different platforms provide different features, and the underlying
be unsupported on another. For consistency's sakes, functions that support functionality Python uses to implement the *dir_fd* parameter is not
*dir_fd* always allow specifying the parameter, but will raise an exception available on all platforms Python supports. For consistency's sake,
if the functionality is not actually available. functions that may support *dir_fd* always allow specifying the
parameter, but will throw an exception if the functionality is used
To check whether a particular function permits use of its *dir_fd* when it's not locally available. (Specifying ``None`` for *dir_fd*
parameter, use the ``in`` operator on ``supports_dir_fd``. As an example, is always supported on all platforms.)
this expression determines whether the *dir_fd* parameter of :func:`os.stat`
is locally available:: To check whether a particular function accepts an open file descriptor
for its *dir_fd* parameter, use the ``in`` operator on ``supports_dir_fd``.
As an example, this expression evaluates to ``True`` if :func:`os.stat`
accepts open file descriptors for *dir_fd* on the local platform::
os.stat in os.supports_dir_fd os.stat in os.supports_dir_fd
Currently *dir_fd* parameters only work on Unix platforms; none of them work Currently *dir_fd* parameters only work on Unix platforms;
on Windows. none of them work on Windows.
.. versionadded:: 3.3 .. versionadded:: 3.3
.. data:: supports_effective_ids .. data:: supports_effective_ids
A :class:`~collections.abc.Set` object indicating which functions in the A :class:`set` object indicating whether :func:`os.access` permits
:mod:`os` module permit use of the *effective_ids* parameter for specifying ``True`` for its *effective_ids* parameter on the local platform.
:func:`os.access`. If the local platform supports it, the collection will (Specifying ``False`` for *effective_ids* is always supported on all
contain :func:`os.access`, otherwise it will be empty. platforms.) If the local platform supports it, the collection will contain
:func:`os.access`; otherwise it will be empty.
To check whether you can use the *effective_ids* parameter for This expression evaluates to ``True`` if :func:`os.access` supports
:func:`os.access`, use the ``in`` operator on ``supports_effective_ids``, ``effective_ids=True`` on the local platform::
like so::
os.access in os.supports_effective_ids os.access in os.supports_effective_ids
Currently *effective_ids* only works on Unix platforms; it does not work on Currently *effective_ids* is only supported on Unix platforms;
Windows. it does not work on Windows.
.. versionadded:: 3.3 .. versionadded:: 3.3
.. data:: supports_fd .. data:: supports_fd
A :class:`~collections.abc.Set` object indicating which functions in the A :class:`set` object indicating which functions in the
:mod:`os` module permit specifying their *path* parameter as an open file :mod:`os` module permit specifying their *path* parameter as an open file
descriptor. Different platforms provide different functionality, and an descriptor on the local platform. Different platforms provide different
option that might work on one might be unsupported on another. For features, and the underlying functionality Python uses to accept open file
consistency's sakes, functions that support *fd* always allow specifying descriptors as *path* arguments is not available on all platforms Python
the parameter, but will raise an exception if the functionality is not supports.
actually available.
To check whether a particular function permits specifying an open file To determine whether a particular function permits specifying an open file
descriptor for its *path* parameter, use the ``in`` operator on descriptor for its *path* parameter, use the ``in`` operator on
``supports_fd``. As an example, this expression determines whether ``supports_fd``. As an example, this expression evaluates to ``True`` if
:func:`os.chdir` accepts open file descriptors when called on your local :func:`os.chdir` accepts open file descriptors for *path* on your local
platform:: platform::
os.chdir in os.supports_fd os.chdir in os.supports_fd
...@@ -2672,17 +2678,21 @@ features: ...@@ -2672,17 +2678,21 @@ features:
.. data:: supports_follow_symlinks .. data:: supports_follow_symlinks
A :class:`~collections.abc.Set` object indicating which functions in the A :class:`set` object indicating which functions in the :mod:`os` module
:mod:`os` module permit use of their *follow_symlinks* parameter. Different accept ``False`` for their *follow_symlinks* parameter on the local platform.
platforms provide different functionality, and an option that might work on Different platforms provide different features, and the underlying
one might be unsupported on another. For consistency's sakes, functions that functionality Python uses to implement *follow_symlinks* is not available
support *follow_symlinks* always allow specifying the parameter, but will on all platforms Python supports. For consistency's sake, functions that
raise an exception if the functionality is not actually available. may support *follow_symlinks* always allow specifying the parameter, but
will throw an exception if the functionality is used when it's not locally
To check whether a particular function permits use of its *follow_symlinks* available. (Specifying ``True`` for *follow_symlinks* is always supported
parameter, use the ``in`` operator on ``supports_follow_symlinks``. As an on all platforms.)
example, this expression determines whether the *follow_symlinks* parameter
of :func:`os.stat` is locally available:: To check whether a particular function accepts ``False`` for its
*follow_symlinks* parameter, use the ``in`` operator on
``supports_follow_symlinks``. As an example, this expression evaluates
to ``True`` if you may specify ``follow_symlinks=False`` when calling
:func:`os.stat` on the local platform::
os.stat in os.supports_follow_symlinks os.stat in os.supports_follow_symlinks
...@@ -2801,7 +2811,7 @@ features: ...@@ -2801,7 +2811,7 @@ features:
following symlinks <follow_symlinks>`. following symlinks <follow_symlinks>`.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*, Added support for specifying *path* as an open file descriptor,
and the *dir_fd*, *follow_symlinks*, and *ns* parameters. and the *dir_fd*, *follow_symlinks*, and *ns* parameters.
.. versionchanged:: 3.6 .. versionchanged:: 3.6
...@@ -3162,7 +3172,7 @@ to be ignored. ...@@ -3162,7 +3172,7 @@ to be ignored.
.. availability:: Unix, Windows. .. availability:: Unix, Windows.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying an open file descriptor for *path* Added support for specifying *path* as an open file descriptor
for :func:`execve`. for :func:`execve`.
.. versionchanged:: 3.6 .. versionchanged:: 3.6
......
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