Issue #23391: Restore OSError constructor argument documentation

This restores details lost in revision 097f4fda61a4 (since Python 3.3,
related to the new OSError subclasses). Further additions:

* Markup for attributes and constructor signature
* Explain "winerror" and "filename2"
* Extend test to check for filename2 defaulting to None
* Clarify that the constructor can return a subclass

I have intentionally left out any details of allowing more than five
arguments, or how the "args" attribute is set for four or more arguments.
These details seem to be dependent on the Python version and platform.

1 files changed, 12 insertions, 5 deletions

diff --git a/Lib/test/test_exceptions.py b/Lib/test/test_exceptions.py
index 80d4f1aeb5..d9543028bb 100644
--- a/Lib/test/test_exceptions.py
+++ b/Lib/test/test_exceptions.py
@@ -230,6 +230,7 @@ class ExceptionTests(unittest.TestCase):
             self.assertEqual(w.winerror, 3)
             self.assertEqual(w.strerror, 'foo')
             self.assertEqual(w.filename, 'bar')
+            self.assertEqual(w.filename2, None)
             self.assertEqual(str(w), "[WinError 3] foo: 'bar'")
             # Unknown win error becomes EINVAL (22)
             w = OSError(0, 'foo', None, 1001)
@@ -237,6 +238,7 @@ class ExceptionTests(unittest.TestCase):
             self.assertEqual(w.winerror, 1001)
             self.assertEqual(w.strerror, 'foo')
             self.assertEqual(w.filename, None)
+            self.assertEqual(w.filename2, None)
             self.assertEqual(str(w), "[WinError 1001] foo")
             # Non-numeric "errno"
             w = OSError('bar', 'foo')
@@ -244,6 +246,7 @@ class ExceptionTests(unittest.TestCase):
             self.assertEqual(w.winerror, None)
             self.assertEqual(w.strerror, 'foo')
             self.assertEqual(w.filename, None)
+            self.assertEqual(w.filename2, None)
 
     @unittest.skipUnless(sys.platform == 'win32',
                          'test specific to Windows')
@@ -268,13 +271,15 @@ class ExceptionTests(unittest.TestCase):
             (SystemExit, ('foo',),
                 {'args' : ('foo',), 'code' : 'foo'}),
             (OSError, ('foo',),
-                {'args' : ('foo',), 'filename' : None,
+                {'args' : ('foo',), 'filename' : None, 'filename2' : None,
                  'errno' : None, 'strerror' : None}),
             (OSError, ('foo', 'bar'),
-                {'args' : ('foo', 'bar'), 'filename' : None,
+                {'args' : ('foo', 'bar'),
+                 'filename' : None, 'filename2' : None,
                  'errno' : 'foo', 'strerror' : 'bar'}),
             (OSError, ('foo', 'bar', 'baz'),
-                {'args' : ('foo', 'bar'), 'filename' : 'baz',
+                {'args' : ('foo', 'bar'),
+                 'filename' : 'baz', 'filename2' : None,
                  'errno' : 'foo', 'strerror' : 'bar'}),
             (OSError, ('foo', 'bar', 'baz', None, 'quux'),
                 {'args' : ('foo', 'bar'), 'filename' : 'baz', 'filename2': 'quux'}),
@@ -284,7 +289,8 @@ class ExceptionTests(unittest.TestCase):
                  'filename' : 'filenameStr'}),
             (OSError, (1, 'strErrorStr', 'filenameStr'),
                 {'args' : (1, 'strErrorStr'), 'errno' : 1,
-                 'strerror' : 'strErrorStr', 'filename' : 'filenameStr'}),
+                 'strerror' : 'strErrorStr',
+                 'filename' : 'filenameStr', 'filename2' : None}),
             (SyntaxError, (), {'msg' : None, 'text' : None,
                 'filename' : None, 'lineno' : None, 'offset' : None,
                 'print_file_and_line' : None}),
@@ -340,7 +346,8 @@ class ExceptionTests(unittest.TestCase):
                 (WindowsError, (1, 'strErrorStr', 'filenameStr'),
                     {'args' : (1, 'strErrorStr'),
                      'strerror' : 'strErrorStr', 'winerror' : None,
-                     'errno' : 1, 'filename' : 'filenameStr'})
+                     'errno' : 1,
+                     'filename' : 'filenameStr', 'filename2' : None})
             )
         except NameError:
             pass