bpo-31412: wave.open takes a path-like object

Doc/library/wave.rst

@@ -19,8 +19,8 @@ The :mod:`wave` module defines the following function and exception:
 
 .. function:: open(file, mode=None)
 
-   If *file* is a string, open the file by that name, otherwise treat it as a
-   file-like object.  *mode* can be:
+   If *file* is a string or :term:`path-like object`, open the file
+   by that name, otherwise treat it as a file-like object.  *mode* can be:
 
    ``'rb'``
       Read only mode.
@@ -47,6 +47,9 @@ The :mod:`wave` module defines the following function and exception:
    .. versionchanged:: 3.4
       Added support for unseekable files.
 
+   .. versionchanged:: 3.7
+      Added support for :term:`path-like object`.
+
 .. function:: openfp(file, mode)
 
    A synonym for :func:`.open`, maintained for backwards compatibility.

Lib/test/test_wave.py

@@ -2,10 +2,12 @@
 from test import audiotests
 from test import support
 from audioop import byteswap
+import io
+import pathlib
+import os
 import sys
 import wave
 
-
 class WaveTest(audiotests.AudioWriteTests,
                audiotests.AudioTestsWithSourceFile):
     module = wave
@@ -108,6 +110,26 @@ def test__all__(self):
         blacklist = {'WAVE_FORMAT_PCM'}
         support.check__all__(self, wave, blacklist=blacklist)
 
+    def test_open(self):
+        # test that a.wave file could in theory be opened.
+        # For file size reasons, we do not have an actual .wav file,
+        # so we will pass in this file, but check that a
+        # a wave.Error (invalid data) will be raised,
+        # and not a TypeError or AttributeError
+        # showing that the opening was actually completed.
+        this_file = os.path.abspath(__file__)
+
+        with self.assertRaises(wave.Error):
+            wave.open(this_file)
+
+        this_file_as_path = pathlib.Path(this_file)
+        with self.assertRaises(wave.Error):
+            wave.open(this_file_as_path)
+
+        this_string_io = io.StringIO()
+        with self.assertRaises(EOFError):
+            wave.open(this_string_io)
+
 
 if __name__ == '__main__':
     unittest.main()

Lib/wave.py

@@ -1,13 +1,14 @@
-"""Stuff to parse WAVE files.
+"""Module for parsing WAVE audio files.
 
 Usage.
 
 Reading WAVE files:
       f = wave.open(file, 'r')
-where file is either the name of a file or an open file pointer.
-The open file pointer must have methods read(), seek(), and close().
-When the setpos() and rewind() methods are not used, the seek()
-method is not  necessary.
+where file is either a str, bytes, or Pathlike object
+representing a file or an open file pointer.
+The open file pointer must have methods read(), and close().
+If the setpos() and rewind() methods are used, then a seek()
+method is also necessary.
 
 This returns an instance of a class with the following public methods:
       getnchannels()  -- returns number of audio channels (1 for
@@ -37,9 +38,11 @@
 
 Writing WAVE files:
       f = wave.open(file, 'w')
-where file is either the name of a file or an open file pointer.
-The open file pointer must have methods write(), tell(), seek(), and
-close().
+where file is either a str, bytes, or Pathlike object
+representing a file or an open file pointer.
+The open file pointer must have methods write(), tell(),  and
+close(). If the pointer does not have a seek() method, then
+setnframes() must be given an accurate value
 
 This returns an instance of a class with the following public methods:
       setnchannels(n) -- set the number of channels
@@ -83,6 +86,7 @@ class Error(Exception):
 _array_fmts = None, 'b', 'h', None, 'i'
 
 import audioop
+import os
 import struct
 import sys
 from chunk import Chunk
@@ -495,6 +499,13 @@ def open(f, mode=None):
             mode = f.mode
         else:
             mode = 'rb'
+    try:
+        f = os.fspath(f)
+    except TypeError:
+        if not hasattr(f, 'read') or not hasattr(f, 'close'):
+            raise TypeError('open() takes str, bytes, a PathLike object, '
+                            + f'or an open filehandle, not {type(f)}')
+
     if mode in ('r', 'rb'):
         return Wave_read(f)
     elif mode in ('w', 'wb'):

Misc/NEWS.d/next/Library/2017-09-10-15-20-14.bpo-31412.lNbm-A.rst

@@ -0,0 +1,2 @@
+`wave.open()` now accepts PathLike objects. Contributed by Michael Scott
+Cuthbert.