CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 519 – Adding a file system path protocol | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0519/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 519 – Adding a file system path protocol | peps.python.org'> <meta property="og:description" content="This PEP proposes a protocol for classes which represent a file system path to be able to provide a str or bytes representation. Changes to Python’s standard library are also proposed to utilize this protocol where appropriate to facilitate the use of p..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0519/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP proposes a protocol for classes which represent a file system path to be able to provide a str or bytes representation. Changes to Python’s standard library are also proposed to utilize this protocol where appropriate to facilitate the use of p..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 519</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 519 – Adding a file system path protocol</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Brett Cannon <brett at python.org>, Koos Zevenhoven <k7hoven at gmail.com></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">11-May-2016</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.6</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">11-May-2016, 12-May-2016, 13-May-2016</dd> <dt class="field-odd">Resolution:</dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2016-May/144646.html">Python-Dev message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#protocol">Protocol</a></li> <li><a class="reference internal" href="#standard-library-changes">Standard library changes</a><ul> <li><a class="reference internal" href="#builtins">builtins</a></li> <li><a class="reference internal" href="#os">os</a></li> <li><a class="reference internal" href="#os-path">os.path</a></li> <li><a class="reference internal" href="#pathlib">pathlib</a></li> <li><a class="reference internal" href="#c-api">C API</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards compatibility</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#other-names-for-the-protocol-s-method">Other names for the protocol’s method</a></li> <li><a class="reference internal" href="#separate-str-bytes-methods">Separate str/bytes methods</a></li> <li><a class="reference internal" href="#providing-a-path-attribute">Providing a <code class="docutils literal notranslate">path</code> attribute</a></li> <li><a class="reference internal" href="#have-fspath-only-return-strings">Have <code class="docutils literal notranslate">__fspath__()</code> only return strings</a></li> <li><a class="reference internal" href="#a-generic-string-encoding-mechanism">A generic string encoding mechanism</a></li> <li><a class="reference internal" href="#have-fspath-be-an-attribute">Have __fspath__ be an attribute</a></li> <li><a class="reference internal" href="#provide-specific-type-hinting-support">Provide specific type hinting support</a></li> <li><a class="reference internal" href="#provide-os-fspathb">Provide <code class="docutils literal notranslate">os.fspathb()</code></a></li> <li><a class="reference internal" href="#call-fspath-off-of-the-instance">Call <code class="docutils literal notranslate">__fspath__()</code> off of the instance</a></li> </ul> </li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP proposes a protocol for classes which represent a file system path to be able to provide a <code class="docutils literal notranslate">str</code> or <code class="docutils literal notranslate">bytes</code> representation. Changes to Python’s standard library are also proposed to utilize this protocol where appropriate to facilitate the use of path objects where historically only <code class="docutils literal notranslate">str</code> and/or <code class="docutils literal notranslate">bytes</code> file system paths are accepted. The goal is to facilitate the migration of users towards rich path objects while providing an easy way to work with code expecting <code class="docutils literal notranslate">str</code> or <code class="docutils literal notranslate">bytes</code>. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> Historically in Python, file system paths have been represented as strings or bytes. This choice of representation has stemmed from C’s own decision to represent file system paths as <code class="docutils literal notranslate">const char *</code> <a class="footnote-reference brackets" href="#libc-open" id="id1">[3]</a>. While that is a totally serviceable format to use for file system paths, it’s not necessarily optimal. At issue is the fact that while all file system paths can be represented as strings or bytes, not all strings or bytes represent a file system path. This can lead to issues where any e.g. string duck-types to a file system path whether it actually represents a path or not. To help elevate the representation of file system paths from their representation as strings and bytes to a richer object representation, the pathlib module <a class="footnote-reference brackets" href="#id12" id="id2">[4]</a> was provisionally introduced in Python 3.4 through <a class="pep reference internal" href="../pep-0428/" title="PEP 428 – The pathlib module – object-oriented filesystem paths">PEP 428</a>. While considered by some as an improvement over strings and bytes for file system paths, it has suffered from a lack of adoption. Typically the key issue listed for the low adoption rate has been the lack of support in the standard library. This lack of support required users of pathlib to manually convert path objects to strings by calling <code class="docutils literal notranslate">str(path)</code> which many found error-prone. One issue in converting path objects to strings comes from the fact that the only generic way to get a string representation of the path was to pass the object to <code class="docutils literal notranslate">str()</code>. This can pose a problem when done blindly as nearly all Python objects have some string representation whether they are a path or not, e.g. <code class="docutils literal notranslate">str(None)</code> will give a result that <code class="docutils literal notranslate">builtins.open()</code> <a class="footnote-reference brackets" href="#builtins-open" id="id3">[5]</a> will happily use to create a new file. Exacerbating this whole situation is the <code class="docutils literal notranslate">DirEntry</code> object <a class="footnote-reference brackets" href="#os-direntry" id="id4">[8]</a>. While path objects have a representation that can be extracted using <code class="docutils literal notranslate">str()</code>, <code class="docutils literal notranslate">DirEntry</code> objects expose a <code class="docutils literal notranslate">path</code> attribute instead. Having no common interface between path objects, <code class="docutils literal notranslate">DirEntry</code>, and any other third-party path library has become an issue. A solution that allows any path-representing object to declare that it is a path and a way to extract a low-level representation that all path objects could support is desired. This PEP then proposes to introduce a new protocol to be followed by objects which represent file system paths. Providing a protocol allows for explicit signaling of what objects represent file system paths as well as a way to extract a lower-level representation that can be used with older APIs which only support strings or bytes. Discussions regarding path objects that led to this PEP can be found in multiple threads on the python-ideas mailing list archive <a class="footnote-reference brackets" href="#python-ideas-archive" id="id5">[1]</a> for the months of March and April 2016 and on the python-dev mailing list archives <a class="footnote-reference brackets" href="#python-dev-archive" id="id6">[2]</a> during April 2016. </section> <section id="proposal"> <h2><a class="toc-backref" href="#proposal" role="doc-backlink">Proposal</a></h2> This proposal is split into two parts. One part is the proposal of a protocol for objects to declare and provide support for exposing a file system path representation. The other part deals with changes to Python’s standard library to support the new protocol. These changes will also lead to the pathlib module dropping its provisional status. <section id="protocol"> <h3><a class="toc-backref" href="#protocol" role="doc-backlink">Protocol</a></h3> The following abstract base class defines the protocol for an object to be considered a path object: <div class="highlight-default notranslate"><div class="highlight"><pre>import abc import typing as t class PathLike(abc.ABC): """Abstract base class for implementing the file system path protocol.""" @abc.abstractmethod def __fspath__(self) -> t.Union[str, bytes]: """Return the file system path representation of the object.""" raise NotImplementedError </pre></div> </div> Objects representing file system paths will implement the <code class="docutils literal notranslate">__fspath__()</code> method which will return the <code class="docutils literal notranslate">str</code> or <code class="docutils literal notranslate">bytes</code> representation of the path. The <code class="docutils literal notranslate">str</code> representation is the preferred low-level path representation as it is human-readable and what people historically represent paths as. </section> <section id="standard-library-changes"> <h3><a class="toc-backref" href="#standard-library-changes" role="doc-backlink">Standard library changes</a></h3> It is expected that most APIs in Python’s standard library that currently accept a file system path will be updated appropriately to accept path objects (whether that requires code or simply an update to documentation will vary). The modules mentioned below, though, deserve specific details as they have either fundamental changes that empower the ability to use path objects, or entail additions/removal of APIs. <section id="builtins"> <h4><a class="toc-backref" href="#builtins" role="doc-backlink">builtins</a></h4> <code class="docutils literal notranslate">open()</code> <a class="footnote-reference brackets" href="#builtins-open" id="id7">[5]</a> will be updated to accept path objects as well as continue to accept <code class="docutils literal notranslate">str</code> and <code class="docutils literal notranslate">bytes</code>. </section> <section id="os"> <h4><a class="toc-backref" href="#os" role="doc-backlink">os</a></h4> The <code class="docutils literal notranslate">fspath()</code> function will be added with the following semantics: <div class="highlight-default notranslate"><div class="highlight"><pre>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__) </pre></div> </div> The <code class="docutils literal notranslate">os.fsencode()</code> <a class="footnote-reference brackets" href="#os-fsencode" id="id8">[6]</a> and <code class="docutils literal notranslate">os.fsdecode()</code> <a class="footnote-reference brackets" href="#os-fsdecode" id="id9">[7]</a> functions will be updated to accept path objects. As both functions coerce their arguments to <code class="docutils literal notranslate">bytes</code> and <code class="docutils literal notranslate">str</code>, respectively, they will be updated to call <code class="docutils literal notranslate">__fspath__()</code> if present to convert the path object to a <code class="docutils literal notranslate">str</code> or <code class="docutils literal notranslate">bytes</code> representation, and then perform their appropriate coercion operations as if the return value from <code class="docutils literal notranslate">__fspath__()</code> had been the original argument to the coercion function in question. The addition of <code class="docutils literal notranslate">os.fspath()</code>, the updates to <code class="docutils literal notranslate">os.fsencode()</code>/<code class="docutils literal notranslate">os.fsdecode()</code>, and the current semantics of <code class="docutils literal notranslate">pathlib.PurePath</code> provide the semantics necessary to get the path representation one prefers. For a path object, <code class="docutils literal notranslate">pathlib.PurePath</code>/<code class="docutils literal notranslate">Path</code> can be used. To obtain the <code class="docutils literal notranslate">str</code> or <code class="docutils literal notranslate">bytes</code> representation without any coercion, then <code class="docutils literal notranslate">os.fspath()</code> can be used. If a <code class="docutils literal notranslate">str</code> is desired and the encoding of <code class="docutils literal notranslate">bytes</code> should be assumed to be the default file system encoding, then <code class="docutils literal notranslate">os.fsdecode()</code> should be used. If a <code class="docutils literal notranslate">bytes</code> representation is desired and any strings should be encoded using the default file system encoding, then <code class="docutils literal notranslate">os.fsencode()</code> is used. This PEP recommends using path objects when possible and falling back to string paths as necessary and using <code class="docutils literal notranslate">bytes</code> 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 <code class="docutils literal notranslate">pathlib.PurePath</code> class can promote a <code class="docutils literal notranslate">str</code> to a path object. The <code class="docutils literal notranslate">os.fspath()</code> function can demote a path object to a <code class="docutils literal notranslate">str</code> or <code class="docutils literal notranslate">bytes</code> instance, depending on what <code class="docutils literal notranslate">__fspath__()</code> returns. The <code class="docutils literal notranslate">os.fsdecode()</code> function will demote a path object to a string or promote a <code class="docutils literal notranslate">bytes</code> object to a <code class="docutils literal notranslate">str</code>. The <code class="docutils literal notranslate">os.fsencode()</code> function will demote a path or string object to <code class="docutils literal notranslate">bytes</code>. There is no function that provides a way to demote a path object directly to <code class="docutils literal notranslate">bytes</code> while bypassing string demotion. The <code class="docutils literal notranslate">DirEntry</code> object <a class="footnote-reference brackets" href="#os-direntry" id="id10">[8]</a> will gain an <code class="docutils literal notranslate">__fspath__()</code> method. It will return the same value as currently found on the <code class="docutils literal notranslate">path</code> attribute of <code class="docutils literal notranslate">DirEntry</code> instances. The <a class="reference internal" href="#protocol">Protocol</a> ABC will be added to the <code class="docutils literal notranslate">os</code> module under the name <code class="docutils literal notranslate">os.PathLike</code>. </section> <section id="os-path"> <h4><a class="toc-backref" href="#os-path" role="doc-backlink">os.path</a></h4> The various path-manipulation functions of <code class="docutils literal notranslate">os.path</code> <a class="footnote-reference brackets" href="#id13" id="id11">[9]</a> will be updated to accept path objects. For polymorphic functions that accept both bytes and strings, they will be updated to simply use <code class="docutils literal notranslate">os.fspath()</code>. During the discussions leading up to this PEP it was suggested that <code class="docutils literal notranslate">os.path</code> not be updated using an “explicit is better than implicit” argument. The thinking was that since <code class="docutils literal notranslate">__fspath__()</code> is polymorphic itself it may be better to have code working with <code class="docutils literal notranslate">os.path</code> 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 <code class="docutils literal notranslate">os.path</code> functions could be used in a tight loop and the overhead of checking or calling <code class="docutils literal notranslate">__fspath__()</code> would be too costly. In this scenario only path-consuming APIs would be directly updated and path-manipulating APIs like the ones in <code class="docutils literal notranslate">os.path</code> 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. </section> <section id="pathlib"> <h4><a class="toc-backref" href="#pathlib" role="doc-backlink">pathlib</a></h4> The constructor for <code class="docutils literal notranslate">pathlib.PurePath</code> and <code class="docutils literal notranslate">pathlib.Path</code> will be updated to accept <code class="docutils literal notranslate">PathLike</code> objects. Both <code class="docutils literal notranslate">PurePath</code> and <code class="docutils literal notranslate">Path</code> will continue to not accept <code class="docutils literal notranslate">bytes</code> path representations, and so if <code class="docutils literal notranslate">__fspath__()</code> returns <code class="docutils literal notranslate">bytes</code> it will raise an exception. The <code class="docutils literal notranslate">path</code> 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). </section> <section id="c-api"> <h4><a class="toc-backref" href="#c-api" role="doc-backlink">C API</a></h4> The C API will gain an equivalent function to <code class="docutils literal notranslate">os.fspath()</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>/* 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; } </pre></div> </div> </section> </section> </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards compatibility</a></h2> There are no explicit backwards-compatibility concerns. Unless an object incidentally already defines a <code class="docutils literal notranslate">__fspath__()</code> method there is no reason to expect the pre-existing code to break or expect to have its semantics implicitly changed. Libraries wishing to support path objects and a version of Python prior to Python 3.6 and the existence of <code class="docutils literal notranslate">os.fspath()</code> can use the idiom of <code class="docutils literal notranslate">path.__fspath__() if hasattr(path, "__fspath__") else path</code>. </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> This is the task list for what this PEP proposes to be changed in Python 3.6: <ol class="arabic simple"> <li>Remove the <code class="docutils literal notranslate">path</code> attribute from pathlib (<a class="reference external" href="http://bugs.python.org/issue22570">done</a>)</li> <li>Remove the provisional status of pathlib (<a class="reference external" href="https://hg.python.org/lookup/a5a013ca5687">done</a>)</li> <li>Add <code class="docutils literal notranslate">os.PathLike</code> (<a class="reference external" href="https://hg.python.org/lookup/e672cf63d08a">code</a> and <a class="reference external" href="http://hg.python.org/lookup/6239673d5e1d">docs</a> done)</li> <li>Add <code class="docutils literal notranslate">PyOS_FSPath()</code> (<a class="reference external" href="https://hg.python.org/lookup/780cbe18082e">code</a> and <a class="reference external" href="http://hg.python.org/lookup/cec1f00c538d">docs</a> done)</li> <li>Add <code class="docutils literal notranslate">os.fspath()</code> (<a class="reference external" href="https://hg.python.org/lookup/780cbe18082e">done <done</a>)</li> <li>Update <code class="docutils literal notranslate">os.fsencode()</code> (<a class="reference external" href="https://hg.python.org/lookup/00991aa5fdb5">done</a>)</li> <li>Update <code class="docutils literal notranslate">os.fsdecode()</code> (<a class="reference external" href="https://hg.python.org/lookup/00991aa5fdb5">done</a>)</li> <li>Update <code class="docutils literal notranslate">pathlib.PurePath</code> and <code class="docutils literal notranslate">pathlib.Path</code> (<a class="reference external" href="https://hg.python.org/lookup/a5a013ca5687">done</a>)<ol class="arabic simple"> <li>Add <code class="docutils literal notranslate">__fspath__()</code></li> <li>Add <code class="docutils literal notranslate">os.PathLike</code> support to the constructors</li> </ol> </li> <li>Add <code class="docutils literal notranslate">__fspath__()</code> to <code class="docutils literal notranslate">DirEntry</code> (<a class="reference external" href="https://hg.python.org/lookup/5a62d682636e">done</a>)</li> <li>Update <code class="docutils literal notranslate">builtins.open()</code> (<a class="reference external" href="https://hg.python.org/lookup/254125a265d2">done</a>)</li> <li>Update <code class="docutils literal notranslate">os.path</code> (<a class="reference external" href="https://hg.python.org/cpython/rev/b64f83d6ff24">done</a>)</li> <li>Add a <a class="reference external" href="https://docs.python.org/3.6/glossary.html">glossary</a> entry for “path-like” (<a class="reference external" href="https://hg.python.org/lookup/9c57178f13dc">done</a>)</li> <li>Update <a class="reference external" href="https://docs.python.org/3.6/whatsnew/3.6.html">“What’s New”</a> (<a class="reference external" href="https://hg.python.org/cpython/rev/95361959d451">done</a>)</li> </ol> </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="other-names-for-the-protocol-s-method"> <h3><a class="toc-backref" href="#other-names-for-the-protocol-s-method" role="doc-backlink">Other names for the protocol’s method</a></h3> Various names were proposed during discussions leading to this PEP, including <code class="docutils literal notranslate">__path__</code>, <code class="docutils literal notranslate">__pathname__</code>, and <code class="docutils literal notranslate">__fspathname__</code>. In the end people seemed to gravitate towards <code class="docutils literal notranslate">__fspath__</code> for being unambiguous without being unnecessarily long. </section> <section id="separate-str-bytes-methods"> <h3><a class="toc-backref" href="#separate-str-bytes-methods" role="doc-backlink">Separate str/bytes methods</a></h3> At one point it was suggested that <code class="docutils literal notranslate">__fspath__()</code> only return strings and another method named <code class="docutils literal notranslate">__fspathb__()</code> be introduced to return bytes. The thinking is that by making <code class="docutils literal notranslate">__fspath__()</code> not be polymorphic it could make dealing with the potential string or bytes representations easier. But the general consensus was that returning bytes will more than likely be rare and that the various functions in the os module are the better abstraction to promote over direct calls to <code class="docutils literal notranslate">__fspath__()</code>. </section> <section id="providing-a-path-attribute"> <h3><a class="toc-backref" href="#providing-a-path-attribute" role="doc-backlink">Providing a <code class="docutils literal notranslate">path</code> attribute</a></h3> To help deal with the issue of <code class="docutils literal notranslate">pathlib.PurePath</code> not inheriting from <code class="docutils literal notranslate">str</code>, originally it was proposed to introduce a <code class="docutils literal notranslate">path</code> attribute to mirror what <code class="docutils literal notranslate">os.DirEntry</code> provides. In the end, though, it was determined that a protocol would provide the same result while not directly exposing an API that most people will never need to interact with directly. </section> <section id="have-fspath-only-return-strings"> <h3><a class="toc-backref" href="#have-fspath-only-return-strings" role="doc-backlink">Have <code class="docutils literal notranslate">__fspath__()</code> only return strings</a></h3> Much of the discussion that led to this PEP revolved around whether <code class="docutils literal notranslate">__fspath__()</code> should be polymorphic and return <code class="docutils literal notranslate">bytes</code> as well as <code class="docutils literal notranslate">str</code> or only return <code class="docutils literal notranslate">str</code>. The general sentiment for this view was that <code class="docutils literal notranslate">bytes</code> are difficult to work with due to their inherent lack of information about their encoding and <a class="pep reference internal" href="../pep-0383/" title="PEP 383 – Non-decodable Bytes in System Character Interfaces">PEP 383</a> makes it possible to represent all file system paths using <code class="docutils literal notranslate">str</code> with the <code class="docutils literal notranslate">surrogateescape</code> handler. Thus, it would be better to forcibly promote the use of <code class="docutils literal notranslate">str</code> as the low-level path representation for high-level path objects. In the end, it was decided that using <code class="docutils literal notranslate">bytes</code> to represent paths is simply not going to go away and thus they should be supported to some degree. The hope is that people will gravitate towards path objects like pathlib and that will move people away from operating directly with <code class="docutils literal notranslate">bytes</code>. </section> <section id="a-generic-string-encoding-mechanism"> <h3><a class="toc-backref" href="#a-generic-string-encoding-mechanism" role="doc-backlink">A generic string encoding mechanism</a></h3> At one point there was a discussion of developing a generic mechanism to extract a string representation of an object that had semantic meaning (<code class="docutils literal notranslate">__str__()</code> does not necessarily return anything of semantic significance beyond what may be helpful for debugging). In the end, it was deemed to lack a motivating need beyond the one this PEP is trying to solve in a specific fashion. </section> <section id="have-fspath-be-an-attribute"> <h3><a class="toc-backref" href="#have-fspath-be-an-attribute" role="doc-backlink">Have __fspath__ be an attribute</a></h3> It was briefly considered to have <code class="docutils literal notranslate">__fspath__</code> be an attribute instead of a method. This was rejected for two reasons. One, historically protocols have been implemented as “magic methods” and not “magic methods and attributes”. Two, there is no guarantee that the lower-level representation of a path object will be pre-computed, potentially misleading users that there was no expensive computation behind the scenes in case the attribute was implemented as a property. This also indirectly ties into the idea of introducing a <code class="docutils literal notranslate">path</code> attribute to accomplish the same thing. This idea has an added issue, though, of accidentally having any object with a <code class="docutils literal notranslate">path</code> attribute meet the protocol’s duck typing. Introducing a new magic method for the protocol helpfully avoids any accidental opting into the protocol. </section> <section id="provide-specific-type-hinting-support"> <h3><a class="toc-backref" href="#provide-specific-type-hinting-support" role="doc-backlink">Provide specific type hinting support</a></h3> There was some consideration to providing a generic <code class="docutils literal notranslate">typing.PathLike</code> class which would allow for e.g. <code class="docutils literal notranslate">typing.PathLike[str]</code> to specify a type hint for a path object which returned a string representation. While potentially beneficial, the usefulness was deemed too small to bother adding the type hint class. This also removed any desire to have a class in the <code class="docutils literal notranslate">typing</code> module which represented the union of all acceptable path-representing types as that can be represented with <code class="docutils literal notranslate">typing.Union[str, bytes, os.PathLike]</code> easily enough and the hope is users will slowly gravitate to path objects only. </section> <section id="provide-os-fspathb"> <h3><a class="toc-backref" href="#provide-os-fspathb" role="doc-backlink">Provide <code class="docutils literal notranslate">os.fspathb()</code></a></h3> It was suggested that to mirror the structure of e.g. <code class="docutils literal notranslate">os.getcwd()</code>/<code class="docutils literal notranslate">os.getcwdb()</code>, that <code class="docutils literal notranslate">os.fspath()</code> only return <code class="docutils literal notranslate">str</code> and that another function named <code class="docutils literal notranslate">os.fspathb()</code> be introduced that only returned <code class="docutils literal notranslate">bytes</code>. This was rejected as the purposes of the <code class="docutils literal notranslate">*b()</code> functions are tied to querying the file system where there is a need to get the raw bytes back. As this PEP does not work directly with data on a file system (but which may be), the view was taken this distinction is unnecessary. It’s also believed that the need for only bytes will not be common enough to need to support in such a specific manner as <code class="docutils literal notranslate">os.fsencode()</code> will provide similar functionality. </section> <section id="call-fspath-off-of-the-instance"> <h3><a class="toc-backref" href="#call-fspath-off-of-the-instance" role="doc-backlink">Call <code class="docutils literal notranslate">__fspath__()</code> off of the instance</a></h3> An earlier draft of this PEP had <code class="docutils literal notranslate">os.fspath()</code> calling <code class="docutils literal notranslate">path.__fspath__()</code> instead of <code class="docutils literal notranslate">type(path).__fspath__(path)</code>. The changed to be consistent with how other magic methods in Python are resolved. </section> </section> <section id="acknowledgements"> <h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2> Thanks to everyone who participated in the various discussions related to this PEP that spanned both python-ideas and python-dev. Special thanks to Stephen Turnbull for direct feedback on early drafts of this PEP. More special thanks to Koos Zevenhoven and Ethan Furman for not only feedback on early drafts of this PEP but also helping to drive the overall discussion on this topic across the two mailing lists. </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="python-ideas-archive" role="doc-footnote"> <dt class="label" id="python-ideas-archive">[<a href="#id5">1</a>]</dt> <dd>The python-ideas mailing list archive (<a class="reference external" href="https://mail.python.org/pipermail/python-ideas/">https://mail.python.org/pipermail/python-ideas/</a>)</aside> <aside class="footnote brackets" id="python-dev-archive" role="doc-footnote"> <dt class="label" id="python-dev-archive">[<a href="#id6">2</a>]</dt> <dd>The python-dev mailing list archive (<a class="reference external" href="https://mail.python.org/pipermail/python-dev/">https://mail.python.org/pipermail/python-dev/</a>)</aside> <aside class="footnote brackets" id="libc-open" role="doc-footnote"> <dt class="label" id="libc-open">[<a href="#id1">3</a>]</dt> <dd><code class="docutils literal notranslate">open()</code> documentation for the C standard library (<a class="reference external" href="http://www.gnu.org/software/libc/manual/html_node/Opening-and-Closing-Files.html">http://www.gnu.org/software/libc/manual/html_node/Opening-and-Closing-Files.html</a>)</aside> <aside class="footnote brackets" id="id12" role="doc-footnote"> <dt class="label" id="id12">[<a href="#id2">4</a>]</dt> <dd>The <code class="docutils literal notranslate">pathlib</code> module (<a class="reference external" href="https://docs.python.org/3/library/pathlib.html#module-pathlib">https://docs.python.org/3/library/pathlib.html#module-pathlib</a>)</aside> <aside class="footnote brackets" id="builtins-open" role="doc-footnote"> <dt class="label" id="builtins-open">[5] (<a href='#id3'>1</a>, <a href='#id7'>2</a>) </dt> <dd>The <code class="docutils literal notranslate">builtins.open()</code> function (<a class="reference external" href="https://docs.python.org/3/library/functions.html#open">https://docs.python.org/3/library/functions.html#open</a>)</aside> <aside class="footnote brackets" id="os-fsencode" role="doc-footnote"> <dt class="label" id="os-fsencode">[<a href="#id8">6</a>]</dt> <dd>The <code class="docutils literal notranslate">os.fsencode()</code> function (<a class="reference external" href="https://docs.python.org/3/library/os.html#os.fsencode">https://docs.python.org/3/library/os.html#os.fsencode</a>)</aside> <aside class="footnote brackets" id="os-fsdecode" role="doc-footnote"> <dt class="label" id="os-fsdecode">[<a href="#id9">7</a>]</dt> <dd>The <code class="docutils literal notranslate">os.fsdecode()</code> function (<a class="reference external" href="https://docs.python.org/3/library/os.html#os.fsdecode">https://docs.python.org/3/library/os.html#os.fsdecode</a>)</aside> <aside class="footnote brackets" id="os-direntry" role="doc-footnote"> <dt class="label" id="os-direntry">[8] (<a href='#id4'>1</a>, <a href='#id10'>2</a>) </dt> <dd>The <code class="docutils literal notranslate">os.DirEntry</code> class (<a class="reference external" href="https://docs.python.org/3/library/os.html#os.DirEntry">https://docs.python.org/3/library/os.html#os.DirEntry</a>)</aside> <aside class="footnote brackets" id="id13" role="doc-footnote"> <dt class="label" id="id13">[<a href="#id11">9</a>]</dt> <dd>The <code class="docutils literal notranslate">os.path</code> module (<a class="reference external" href="https://docs.python.org/3/library/os.path.html#module-os.path">https://docs.python.org/3/library/os.path.html#module-os.path</a>)</aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0519.rst">https://github.com/python/peps/blob/main/peps/pep-0519.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0519.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#protocol">Protocol</a></li> <li><a class="reference internal" href="#standard-library-changes">Standard library changes</a><ul> <li><a class="reference internal" href="#builtins">builtins</a></li> <li><a class="reference internal" href="#os">os</a></li> <li><a class="reference internal" href="#os-path">os.path</a></li> <li><a class="reference internal" href="#pathlib">pathlib</a></li> <li><a class="reference internal" href="#c-api">C API</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards compatibility</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#other-names-for-the-protocol-s-method">Other names for the protocol’s method</a></li> <li><a class="reference internal" href="#separate-str-bytes-methods">Separate str/bytes methods</a></li> <li><a class="reference internal" href="#providing-a-path-attribute">Providing a <code class="docutils literal notranslate">path</code> attribute</a></li> <li><a class="reference internal" href="#have-fspath-only-return-strings">Have <code class="docutils literal notranslate">__fspath__()</code> only return strings</a></li> <li><a class="reference internal" href="#a-generic-string-encoding-mechanism">A generic string encoding mechanism</a></li> <li><a class="reference internal" href="#have-fspath-be-an-attribute">Have __fspath__ be an attribute</a></li> <li><a class="reference internal" href="#provide-specific-type-hinting-support">Provide specific type hinting support</a></li> <li><a class="reference internal" href="#provide-os-fspathb">Provide <code class="docutils literal notranslate">os.fspathb()</code></a></li> <li><a class="reference internal" href="#call-fspath-off-of-the-instance">Call <code class="docutils literal notranslate">__fspath__()</code> off of the instance</a></li> </ul> </li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0519.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>