[Python-checkins] cpython (3.4): Issue #23391: Restore OSError constructor argument documentation
martin.panter
python-checkins at python.org
Mon Oct 26 20:00:59 EDT 2015
https://hg.python.org/cpython/rev/cb554248ce54
changeset: 98861:cb554248ce54
branch: 3.4
parent: 98856:168569414215
user: Martin Panter <vadmium+py at gmail.com>
date: Mon Oct 26 11:05:42 2015 +0000
summary:
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.
files:
Doc/library/exceptions.rst | 69 +++++++++++++++++-------
Lib/test/test_exceptions.py | 17 ++++-
2 files changed, 60 insertions(+), 26 deletions(-)
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -231,44 +231,71 @@
classes to override the method.
-.. exception:: OSError
+.. exception:: OSError([arg])
+ OSError(errno, strerror[, filename[, winerror[, filename2]]])
.. index:: module: errno
This exception is raised when a system function returns a system-related
error, including I/O failures such as "file not found" or "disk full"
- (not for illegal argument types or other incidental errors). Often a
- subclass of :exc:`OSError` will actually be raised as described in
- `OS exceptions`_ below. The :attr:`errno` attribute is a numeric error
- code from the C variable :c:data:`errno`.
+ (not for illegal argument types or other incidental errors).
- Under Windows, the :attr:`winerror` attribute gives you the native
- Windows error code. The :attr:`errno` attribute is then an approximate
- translation, in POSIX terms, of that native error code.
+ The second form of the constructor sets the corresponding attributes,
+ described below. The attributes default to :const:`None` if not
+ specified. For backwards compatibility, if three arguments are passed,
+ the :attr:`~BaseException.args` attribute contains only a 2-tuple
+ of the first two constructor arguments.
- Under all platforms, the :attr:`strerror` attribute is the corresponding
- error message as provided by the operating system (as formatted by the C
- functions :c:func:`perror` under POSIX, and :c:func:`FormatMessage`
- Windows).
+ The constructor often actually returns a subclass of :exc:`OSError`, as
+ described in `OS exceptions`_ below. The particular subclass depends on
+ the final :attr:`.errno` value. This behaviour only occurs when
+ constructing :exc:`OSError` directly or via an alias, and is not
+ inherited when subclassing.
- For exceptions that involve a file system path (such as :func:`open` or
- :func:`os.unlink`), the exception instance will contain an additional
- attribute, :attr:`filename`, which is the file name passed to the function.
- For functions that involve two file system paths (such as
- :func:`os.rename`), the exception instance will contain a second
- :attr:`filename2` attribute corresponding to the second file name passed
- to the function.
+ .. attribute:: errno
+
+ A numeric error code from the C variable :c:data:`errno`.
+
+ .. attribute:: winerror
+
+ Under Windows, this gives you the native
+ Windows error code. The :attr:`.errno` attribute is then an approximate
+ translation, in POSIX terms, of that native error code.
+
+ Under Windows, if the *winerror* constructor argument is an integer,
+ the :attr:`.errno` attribute is determined from the Windows error code,
+ and the *errno* argument is ignored. On other platforms, the
+ *winerror* argument is ignored, and the :attr:`winerror` attribute
+ does not exist.
+
+ .. attribute:: strerror
+
+ The corresponding error message, as provided by
+ the operating system. It is formatted by the C
+ functions :c:func:`perror` under POSIX, and :c:func:`FormatMessage`
+ under Windows.
+
+ .. attribute:: filename
+ filename2
+
+ For exceptions that involve a file system path (such as :func:`open` or
+ :func:`os.unlink`), :attr:`filename` is the file name passed to the function.
+ For functions that involve two file system paths (such as
+ :func:`os.rename`), :attr:`filename2` corresponds to the second
+ file name passed to the function.
.. versionchanged:: 3.3
:exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`,
:exc:`VMSError`, :exc:`socket.error`, :exc:`select.error` and
- :exc:`mmap.error` have been merged into :exc:`OSError`.
+ :exc:`mmap.error` have been merged into :exc:`OSError`, and the
+ constructor may return a subclass.
.. versionchanged:: 3.4
The :attr:`filename` attribute is now the original file name passed to
the function, instead of the name encoded to or decoded from the
- filesystem encoding. Also, the :attr:`filename2` attribute was added.
+ filesystem encoding. Also, the *filename2* constructor argument and
+ attribute was added.
.. exception:: OverflowError
diff --git a/Lib/test/test_exceptions.py b/Lib/test/test_exceptions.py
--- a/Lib/test/test_exceptions.py
+++ b/Lib/test/test_exceptions.py
@@ -230,6 +230,7 @@
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 @@
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 @@
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 @@
(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 @@
'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 @@
(WindowsError, (1, 'strErrorStr', 'filenameStr'),
{'args' : (1, 'strErrorStr'),
'strerror' : 'strErrorStr', 'winerror' : None,
- 'errno' : 1, 'filename' : 'filenameStr'})
+ 'errno' : 1,
+ 'filename' : 'filenameStr', 'filename2' : None})
)
except NameError:
pass
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list