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

Fri Jun 24 15:21:52 EDT 2016

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
