diff -r 3ab32f7add6e Doc/whatsnew/3.6.rst --- a/Doc/whatsnew/3.6.rst Fri Aug 19 18:59:15 2016 +0200 +++ b/Doc/whatsnew/3.6.rst Fri Aug 19 15:50:31 2016 -0700 @@ -66,6 +66,10 @@ * PEP 498: :ref:`Formatted string literals ` +Standard library improvements: + +* PEP 519: :ref:`Adding a file system path protocol ` + Windows improvements: * The ``py.exe`` launcher, when used interactively, no longer prefers @@ -92,6 +96,52 @@ New Features ============ +.. _pep-519: + +PEP 519: Adding a file system path protocol +=========================================== + +File system paths have historically been represented as :class:`str` or +:class:`bytes` objects. This has led to people writing code which +operates on file system paths to assume that a path is only one of +those two types (an :class:`int` representing a file descriptor does +not count as that is not a file path). Unfortunately that prevents +alternative object representations of file system paths like +:mod:`pathlib` from working with pre-existing code, including Python's +standard library. + +To fix this situation so that any object can represent a path if it +chooses to, a new interface represented by :class:`os.PathLike` has +been defined. By implementing the :meth:`~os.PathLike.__fspath__` +method, an object signals that it represents a path and can provide a +low-level representation of a file system path as a :class:`str` or +:class:`bytes` object. This means an object is considered +:term:`path-like ` if it implements +:class:`os.PathLike` or is a :class:`str` or :class:`bytes` object +which represents a file system path. Code can use :func:`os.fspath`, +:func:`os.fsdecode`, or :func:`os.fsencode` to get explicitly get a +:class:`str` and/or :class:`bytes` representation of a path-like +object. + +The built-in :func:`open` function has been updated to accept +:class:`os.PathLike` objects as has all relevant functions in the +:mod:`os` and :mod:`os.path` modules. The :class:`os.DirEntry` class +and relevant classes in :mod:`pathlib` have also been updated to +implement :class:`os.PathLike`. The hope is that by updating the +fundamental functions for operating on file system paths will lead +to third-party code to implicitly supporting all +:term:`path-like objects ` without any code changes +or at least very minimal ones (e.g. calling :func:`os.fspath` at the +beginning of code before operating on a path-like object). + +(Implemented by Brett Cannon, Ethan Furman, Dusty Phillips, and Jelle Zijlstra.) + +.. seealso:: + + :pep:`519` - Adding a file system path protocol + PEP written by Brett Cannon and Koos Zevenhoven. + + .. _whatsnew-fstrings: PEP 498: Formatted string literals