[Python-checkins] cpython: issue27186 -- initial docs, tests, and python version of os.fspath

[ethan.furman]

https://hg.python.org/cpython/rev/59a52a9dd0dc
changeset:   101621:59a52a9dd0dc
user:        Ethan Furman <ethan at stoneleaf.us>
date:        Thu Jun 02 15:06:09 2016 -0700
summary:
  issue27186 -- initial docs, tests, and python version of os.fspath

files:
  Doc/library/os.rst  |   9 +++++++++
  Lib/os.py           |  21 +++++++++++++++++++++
  Lib/test/test_os.py |  21 +++++++++++++++++++++
  3 files changed, 51 insertions(+), 0 deletions(-)


diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -186,6 +186,15 @@
    .. 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
diff --git a/Lib/os.py b/Lib/os.py
--- a/Lib/os.py
+++ b/Lib/os.py
@@ -1097,3 +1097,24 @@
         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__)
diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py
--- a/Lib/test/test_os.py
+++ b/Lib/test/test_os.py
@@ -3095,5 +3095,26 @@
             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()

-- 
Repository URL: https://hg.python.org/cpython