Protocol

The following abstract base class defines the protocol for an objectto be considered a path object:

importabcimporttypingastclassPathLike(abc.ABC):"""Abstract base class for implementing the file system path protocol."""@abc.abstractmethoddef__fspath__(self)->t.Union[str,bytes]:"""Return the file system path representation of the object."""raiseNotImplementedError

Objects representing file system paths will implement the__fspath__() method which will return thestr orbytesrepresentation of the path. Thestr representation is thepreferred low-level path representation as it is human-readable andwhat people historically represent paths as.

Standard library changes

It is expected that most APIs in Python’s standard library thatcurrently accept a file system path will be updated appropriately toaccept path objects (whether that requires code or simply an updateto documentation will vary). The modules mentioned below, though,deserve specific details as they have either fundamental changes thatempower the ability to use path objects, or entail additions/removalof APIs.

importtypingastdeffspath(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.    """ifisinstance(path,(str,bytes)):returnpath# Work from the object's type to match method resolution of other magic# methods.path_type=type(path)try:path=path_type.__fspath__(path)exceptAttributeError:ifhasattr(path_type,'__fspath__'):raiseelse:ifisinstance(path,(str,bytes)):returnpathelse:raiseTypeError("expected __fspath__() to return str or bytes, ""not "+type(path).__name__)raiseTypeError("expected str, bytes or os.PathLike object, not "+path_type.__name__)

/*    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;}

Other names for the protocol’s method

Various names were proposed during discussions leading to this PEP,including__path__,__pathname__, and__fspathname__. Inthe end people seemed to gravitate towards__fspath__ for beingunambiguous without being unnecessarily long.

Separate str/bytes methods

At one point it was suggested that__fspath__() only returnstrings and another method named__fspathb__() be introduced toreturn bytes. The thinking is that by making__fspath__() not bepolymorphic it could make dealing with the potential string or bytesrepresentations easier. But the general consensus was that returningbytes will more than likely be rare and that the various functions inthe os module are the better abstraction to promote over directcalls to__fspath__().

Providing apath attribute

To help deal with the issue ofpathlib.PurePath not inheritingfromstr, originally it was proposed to introduce apathattribute to mirror whatos.DirEntry provides. In the end,though, it was determined that a protocol would provide the sameresult while not directly exposing an API that most people will neverneed to interact with directly.

Have__fspath__() only return strings

Much of the discussion that led to this PEP revolved around whether__fspath__() should be polymorphic and returnbytes as well asstr or only returnstr. The general sentiment for this viewwas thatbytes are difficult to work with due to theirinherent lack of information about their encoding andPEP 383 makesit possible to represent all file system paths usingstr with thesurrogateescape handler. Thus, it would be better to forciblypromote the use ofstr as the low-level path representation forhigh-level path objects.

In the end, it was decided that usingbytes to represent paths issimply not going to go away and thus they should be supported to somedegree. The hope is that people will gravitate towards path objectslike pathlib and that will move people away from operating directlywithbytes.

A generic string encoding mechanism

At one point there was a discussion of developing a generic mechanismto extract a string representation of an object that had semanticmeaning (__str__() does not necessarily return anything ofsemantic significance beyond what may be helpful for debugging). Inthe end, it was deemed to lack a motivating need beyond the one thisPEP is trying to solve in a specific fashion.

Have __fspath__ be an attribute

It was briefly considered to have__fspath__ be an attributeinstead of a method. This was rejected for two reasons. One,historically protocols have been implemented as “magic methods” andnot “magic methods and attributes”. Two, there is no guarantee thatthe lower-level representation of a path object will be pre-computed,potentially misleading users that there was no expensive computationbehind the scenes in case the attribute was implemented as a property.

This also indirectly ties into the idea of introducing apathattribute to accomplish the same thing. This idea has an added issue,though, of accidentally having any object with apath attributemeet the protocol’s duck typing. Introducing a new magic method forthe protocol helpfully avoids any accidental opting into the protocol.

Provide specific type hinting support

There was some consideration to providing a generictyping.PathLikeclass which would allow for e.g.typing.PathLike[str] to specifya type hint for a path object which returned a string representation.While potentially beneficial, the usefulness was deemed too small tobother adding the type hint class.

This also removed any desire to have a class in thetyping modulewhich represented the union of all acceptable path-representing typesas that can be represented withtyping.Union[str,bytes,os.PathLike] easily enough and the hopeis users will slowly gravitate to path objects only.

Provideos.fspathb()

It was suggested that to mirror the structure of e.g.os.getcwd()/os.getcwdb(), thatos.fspath() only returnstr and that another function namedos.fspathb() beintroduced that only returnedbytes. This was rejected as thepurposes of the*b() functions are tied to querying the filesystem where there is a need to get the raw bytes back. As this PEPdoes not work directly with data on a file system (but whichmaybe), the view was taken this distinction is unnecessary. It’s alsobelieved that the need for only bytes will not be common enough toneed to support in such a specific manner asos.fsencode() willprovide similar functionality.

Call__fspath__() off of the instance

An earlier draft of this PEP hados.fspath() callingpath.__fspath__() instead oftype(path).__fspath__(path). Thechanged to be consistent with how other magic methods in Python areresolved.