Issue #27186: Define what a "path-like object" is.

Thanks to Dusty Phillips for the initial patch.

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 43af006a4744a18cb489adf254fab19b11305244..fe175951c89447c3d72ee6400a88c9e32191d422 100644 (file)
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -778,6 +778,16 @@ Glossary
       One of the default :term:`meta path finders <meta path finder>` which
       searches an :term:`import path` for modules.
 
+   path-like object
+      An object representing a file system path. A path-like object is either
+      a :class:`str` or :class:`bytes` object representing a path, or an object
+      implementing the :class:`os.PathLike` protocol. An object that supports
+      the :class:`os.PathLike` protocol can be converted to a :class:`str` or
+      :class:`bytes` file system path by calling the :func:`os.fspath` function;
+      :func:`os.fsdecode` and :func:`os.fsencode` can be used to guarantee a
+      :class:`str` or :class:`bytes` result instead, respectively. Introduced
+      by :pep:`519`.
+
    portion
       A set of files in a single directory (possibly stored in a zip file)
       that contribute to a namespace package, as defined in :pep:`420`.

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 0346cc22a0dde18d87ec23256aa4a5dcbbb2748e..e7cf4fa835da65849b894ad3e817dcfb4861269e 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -171,8 +171,9 @@ 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.
 
@@ -185,8 +186,9 @@ process and user.
 
 .. 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.
 
@@ -2003,8 +2005,8 @@ features:
    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 path-like object, ``DirEntry`` implements the
-   :class:`os.PathLike` interface.
+   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:
 
@@ -2112,7 +2114,7 @@ features:
 
    Note that there is a nice correspondence between several attributes
    and methods of ``DirEntry`` and of :class:`pathlib.Path`.  In
-   particular, the ``name`` and ``path`` attributes have the same
+   particular, the ``name`` attribute has the same
    meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()``
    and ``stat()`` methods.