[Python-checkins] cpython: Issue #27186: Define what a "path-like object" is.

[brett.cannon]

https://hg.python.org/cpython/rev/9c57178f13dc
changeset:   102161:9c57178f13dc
user:        Brett Cannon <brett at python.org>
date:        Fri Jun 24 12:21:47 2016 -0700
summary:
  Issue #27186: Define what a "path-like object" is.

Thanks to Dusty Phillips for the initial patch.

files:
  Doc/glossary.rst   |  10 ++++++++++
  Doc/library/os.rst |  16 +++++++++-------
  2 files changed, 19 insertions(+), 7 deletions(-)


diff --git a/Doc/glossary.rst b/Doc/glossary.rst
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -778,6 +778,16 @@
       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
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -171,8 +171,9 @@
 
 .. 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 @@
 
 .. 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 @@
    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 @@
 
    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.
 

-- 
Repository URL: https://hg.python.org/cpython