builtins

open() [5] will be updated to accept path objects as well as continue to accept str and bytes.

os

The fspath() function will be added with the following semantics:

import typing as t


def fspath(path: t.Union[PathLike, str, bytes]) -> t.Union[str, bytes]:
    """Return the string representation of the path.

    If str or bytes is passed in, it is returned unchanged. If __fspath__()
    returns something other than str or bytes then TypeError is raised. If
    this function is given something that is not str, bytes, or os.PathLike
    then TypeError is raised.
    """
    if isinstance(path, (str, bytes)):
        return path

    # Work from the object's type to match method resolution of other magic
    # methods.
    path_type = type(path)
    try:
        path = path_type.__fspath__(path)
    except AttributeError:
        if hasattr(path_type, '__fspath__'):
            raise
    else:
        if isinstance(path, (str, bytes)):
            return path
        else:
            raise TypeError("expected __fspath__() to return str or bytes, "
                            "not " + type(path).__name__)

    raise TypeError("expected str, bytes or os.PathLike object, not "
                    + path_type.__name__)

The os.fsencode() [6] and os.fsdecode() [7] functions will be updated to accept path objects. As both functions coerce their arguments to bytes and str, respectively, they will be updated to call __fspath__() if present to convert the path object to a str or bytes representation, and then perform their appropriate coercion operations as if the return value from __fspath__() had been the original argument to the coercion function in question.

The addition of os.fspath(), the updates to os.fsencode()/os.fsdecode(), and the current semantics of pathlib.PurePath provide the semantics necessary to get the path representation one prefers. For a path object, pathlib.PurePath/Path can be used. To obtain the str or bytes representation without any coersion, then os.fspath() can be used. If a str is desired and the encoding of bytes should be assumed to be the default file system encoding, then os.fsdecode() should be used. If a bytes representation is desired and any strings should be encoded using the default file system encoding, then os.fsencode() is used. This PEP recommends using path objects when possible and falling back to string paths as necessary and using bytes as a last resort.

Another way to view this is as a hierarchy of file system path representations (highest- to lowest-level): path → str → bytes. The functions and classes under discussion can all accept objects on the same level of the hierarchy, but they vary in whether they promote or demote objects to another level. The pathlib.PurePath class can promote a str to a path object. The os.fspath() function can demote a path object to a str or bytes instance, depending on what __fspath__() returns. The os.fsdecode() function will demote a path object to a string or promote a bytes object to a str. The os.fsencode() function will demote a path or string object to bytes. There is no function that provides a way to demote a path object directly to bytes while bypassing string demotion.

The DirEntry object [8] will gain an __fspath__() method. It will return the same value as currently found on the path attribute of DirEntry instances.

The Protocol ABC will be added to the os module under the name os.PathLike.

os.path

The various path-manipulation functions of os.path [9] will be updated to accept path objects. For polymorphic functions that accept both bytes and strings, they will be updated to simply use os.fspath().

During the discussions leading up to this PEP it was suggested that os.path not be updated using an "explicit is better than implicit" argument. The thinking was that since __fspath__() is polymorphic itself it may be better to have code working with os.path extract the path representation from path objects explicitly. There is also the consideration that adding support this deep into the low-level OS APIs will lead to code magically supporting path objects without requiring any documentation updated, leading to potential complaints when it doesn't work, unbeknownst to the project author.

But it is the view of this PEP that "practicality beats purity" in this instance. To help facilitate the transition to supporting path objects, it is better to make the transition as easy as possible than to worry about unexpected/undocumented duck typing support for path objects by projects.

There has also been the suggestion that os.path functions could be used in a tight loop and the overhead of checking or calling __fspath__() would be too costly. In this scenario only path-consuming APIs would be directly updated and path-manipulating APIs like the ones in os.path would go unmodified. This would require library authors to update their code to support path objects if they performed any path manipulations, but if the library code passed the path straight through then the library wouldn't need to be updated. It is the view of this PEP and Guido, though, that this is an unnecessary worry and that performance will still be acceptable.

pathlib

The constructor for pathlib.PurePath and pathlib.Path will be updated to accept PathLike objects. Both PurePath and Path will continue to not accept bytes path representations, and so if __fspath__() returns bytes it will raise an exception.

The path attribute will be removed as this PEP makes it redundant (it has not been included in any released version of Python and so is not a backwards-compatibility concern).

C API

The C API will gain an equivalent function to os.fspath():

/*
    Return the file system path representation of the object.

    If the object is str or bytes, then allow it to pass through with
    an incremented refcount. If the object defines __fspath__(), then
    return the result of that method. All other types raise a TypeError.
*/
PyObject *
PyOS_FSPath(PyObject *path)
{
    _Py_IDENTIFIER(__fspath__);
    PyObject *func = NULL;
    PyObject *path_repr = NULL;

    if (PyUnicode_Check(path) || PyBytes_Check(path)) {
        Py_INCREF(path);
        return path;
    }

    func = _PyObject_LookupSpecial(path, &PyId___fspath__);
    if (NULL == func) {
        return PyErr_Format(PyExc_TypeError,
                            "expected str, bytes or os.PathLike object, "
                            "not %S",
                            path->ob_type);
    }

    path_repr = PyObject_CallFunctionObjArgs(func, NULL);
    Py_DECREF(func);
    if (!PyUnicode_Check(path_repr) && !PyBytes_Check(path_repr)) {
        Py_DECREF(path_repr);
        return PyErr_Format(PyExc_TypeError,
                            "expected __fspath__() to return str or bytes, "
                            "not %S",
                            path_repr->ob_type);
    }

    return path_repr;
}