[Python-checkins] peps: OSError will be the canonical name, not IOError

[antoine.pitrou]

http://hg.python.org/peps/rev/5f4cca98db9d
changeset:   3937:5f4cca98db9d
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Mon Aug 29 18:36:36 2011 +0200
summary:
  OSError will be the canonical name, not IOError

files:
  pep-3151.txt |  43 +++++++++++++++++++++------------------
  1 files changed, 23 insertions(+), 20 deletions(-)


diff --git a/pep-3151.txt b/pep-3151.txt
--- a/pep-3151.txt
+++ b/pep-3151.txt
@@ -228,11 +228,11 @@
 The first step of the resolution is to coalesce existing exception types.
 The following changes are proposed:
 
-* alias both socket.error and select.error to IOError
+* alias both socket.error and select.error to OSError
 * alias mmap.error to OSError
 * alias both WindowsError and VMSError to OSError
-* alias OSError to IOError
-* coalesce EnvironmentError into IOError
+* alias IOError to OSError
+* coalesce EnvironmentError into OSError
 
 Each of these changes doesn't preserve exact compatibility, but it does
 preserve *useful compatibility* (see "compatibility" section above).
@@ -242,7 +242,7 @@
 is accepted in full.  In this case, the IO exception sub-hierarchy would
 become::
 
-    +-- IOError   (replacing OSError, WindowsError, EnvironmentError, etc.)
+    +-- OSError   (replacing IOError, WindowsError, EnvironmentError, etc.)
         +-- io.BlockingIOError
         +-- io.UnsupportedOperation (also inherits from ValueError)
         +-- socket.gaierror
@@ -256,13 +256,16 @@
 explained in the rationale_ section, but it also allows for a better
 and more complete resolution of `Step 2`_ (see Prerequisite_).
 
-The rationale for keeping ``IOError`` as the official name for generic
-OS-related exceptions is the survey in `Appendix B`_, which shows it is the
-dominant error today in the standard library.  ``EnvironmentError`` might
-be more accurate, but it is more tedious to type and also much lesser-known.
-As for third-party Python code, Google Code Search shows IOError
-being ten times more popular than EnvironmentError in user code, and
-three times more popular than OSError [3]_.
+The rationale for keeping ``OSError`` as the official name for generic
+OS-related exceptions is that it, precisely, is more generic than ``IOError``.
+``EnvironmentError`` is more tedious to type and also much lesser-known.
+
+The survey in `Appendix B`_ shows that IOError is the dominant
+error today in the standard library.  As for third-party Python code,
+Google Code Search shows IOError being ten times more popular than
+EnvironmentError in user code, and three times more popular than OSError
+[3]_.  However, with no intention to deprecate IOError in the middle
+term, the lesser popularity of OSError is not a problem.
 
 Exception attributes
 --------------------
@@ -270,7 +273,7 @@
 Coalescing WindowsError would mean the ``winerror`` attribute would be
 present on all platforms, just set to ``None`` if the platform
 isn't Windows.  Indeed, ``errno``, ``filename`` and ``strerror`` can all
-already be None, as is often the case when IOError is raised directly
+already be None, as is often the case when OSError is raised directly
 by Python code.
 
 Deprecation of names
@@ -403,7 +406,7 @@
 
 The following drawing tries to sum up the proposed additions, along with
 the corresponding errno values (where applicable).  The root of the
-sub-hierarchy (IOError, assuming `Step 1`_ is accepted in full) is not
+sub-hierarchy (OSError, assuming `Step 1`_ is accepted in full) is not
 shown::
 
     +-- BlockingIOError        EAGAIN, EALREADY, EWOULDBLOCK, EINPROGRESS
@@ -449,15 +452,15 @@
 
 The first possibility is to adapt the ``PyErr_SetFromErrno()`` family
 of functions (``PyErr_SetFromWindowsErr()`` under Windows) to raise the
-appropriate ``IOError`` subclass.  This wouldn't cover, however, Python
-code raising IOError directly, using the following idiom (seen in
+appropriate OSError subclass.  This wouldn't cover, however, Python
+code raising OSError directly, using the following idiom (seen in
 ``Lib/tempfile.py``)::
 
     raise IOError(_errno.EEXIST, "No usable temporary file name found")
 
 A second possibility, suggested by Marc-Andre Lemburg, is to adapt
-``IOError.__new__`` to instantiate the appropriate subclass.  This would
-have the benefit of also covering Python code such as the above.
+``OSError.__new__`` to instantiate the appropriate subclass.  This has
+the benefit of also covering Python code such as the above.
 
 
 Possible objections
@@ -505,16 +508,16 @@
 It has been successfully tested on a variety of systems: Linux, Windows,
 OpenIndiana and FreeBSD buildbots.
 
-One source of trouble has been with the respective constructors of ``IOError``
+One source of trouble has been with the respective constructors of ``OSError``
 and ``WindowsError``, which were incompatible.  The way it is solved is by
-keeping the ``IOError`` signature and adding a fourth optional argument
+keeping the ``OSError`` signature and adding a fourth optional argument
 to allow passing the Windows error code (which is different from the POSIX
 errno).  The fourth argument is stored as ``winerror`` and its POSIX
 translation as ``errno``.  The ``PyErr_SetFromWindowsErr*`` functions have
 been adapted to use the right constructor call.
 
 A slight complication is when the ``PyErr_SetExcFromWindowsErr*`` functions
-are called with ``IOError`` rather than ``WindowsError``: the ``errno``
+are called with ``OSError`` rather than ``WindowsError``: the ``errno``
 attribute of the exception object would store the Windows error code (such
 as 109 for ERROR_BROKEN_PIPE) rather than its POSIX translation (such as 32
 for EPIPE), which it does now.  For non-socket error codes, this only occurs

-- 
Repository URL: http://hg.python.org/peps