issue27186 -- initial docs, tests, and python version of os.fspath

Doc/library/os.rst

@@ -186,6 +186,15 @@ process and user.
    .. versionadded:: 3.2
 
 
+.. function:: fspath(path)
+
+   Return the string representation of the path.
+
+   If :class:`str` or :class:`bytes` is passed in, it is returned unchanged;
+   otherwise, the result of calling ``type(path).__fspath__`` is returned, or an
+   exception is raised.
+
+
 .. function:: getenv(key, default=None)
 
    Return the value of the environment variable *key* if it exists, or

Lib/os.py

@@ -1097,3 +1097,24 @@ def fdopen(fd, *args, **kwargs):
         raise TypeError("invalid fd type (%s, expected integer)" % type(fd))
     import io
     return io.open(fd, *args, **kwargs)
+
+# Supply os.fspath()
+def fspath(path):
+    """Return the string representation of the path.
+
+    If str or bytes is passed in, it is returned unchanged.
+    """
+    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:
+        return path_type.__fspath__(path)
+    except AttributeError:
+        if hasattr(path_type, '__fspath__'):
+            raise
+
+        raise TypeError("expected str, bytes or os.PathLike object, not "
+                        + path_type.__name__)

Lib/test/test_os.py

@@ -3095,5 +3095,26 @@ class TestScandir(unittest.TestCase):
             del iterator
 
 
+class TestPEP519(unittest.TestCase):
+    "os.fspath()"
+
+    def test_return_bytes(self):
+        for b in b'hello', b'goodbye', b'some/path/and/file':
+            self.assertEqual(b, os.fspath(b))
+
+    def test_return_string(self):
+        for s in 'hello', 'goodbye', 'some/path/and/file':
+            self.assertEqual(s, os.fspath(s))
+
+    def test_garbage_in_exception_out(self):
+        vapor = type('blah', (), {})
+        for o in int, type, os, vapor():
+            self.assertRaises(TypeError, os.fspath, o)
+
+    def test_argument_required(self):
+        with self.assertRaises(TypeError):
+            os.fspath()
+
+
 if __name__ == "__main__":
     unittest.main()