[Python-checkins] r83049 - peps/trunk/pep-3151.txt

[antoine.pitrou]

Author: antoine.pitrou
Date: Thu Jul 22 13:41:49 2010
New Revision: 83049

Log:
Nick's input



Modified:
   peps/trunk/pep-3151.txt

Modified: peps/trunk/pep-3151.txt
==============================================================================
--- peps/trunk/pep-3151.txt	(original)
+++ peps/trunk/pep-3151.txt	Thu Jul 22 13:41:49 2010
@@ -95,7 +95,7 @@
 anyway.
 
 .. note::
-    **Appendix B** surveys the use of the various exception types accross
+    `Appendix B`_ surveys the use of the various exception types accross
     the interpreter and the standard library.
 
 
@@ -196,24 +196,55 @@
 Careful code should not be penalized.
 
 
+.. _Step 1:
+
 Step 1: coalesce exception types
 ================================
 
 The first step of the resolution is to coalesce existing exception types.
-The extent of this step is not yet fully determined.  A number of possible
-changes are listed hereafter:
+The following changes are proposed:
 
 * alias both socket.error and select.error to IOError
 * alias mmap.error to OSError
-* alias IOError to OSError
 * alias WindowsError to OSError
+* alias OSError to IOError
+* coalesce EnvironmentError into IOError
 
 Each of these changes doesn't preserve exact compatibility, but it does
 preserve *useful compatibility* (see "compatibility" section above).
 
-Not only does this first step present the user a simpler landscape, but
-it also allows for a better and more complete resolution of step 2
-(see "Prerequisite" below).
+Each of these changes can be accepted or refused invididually, but of course
+it is considered that the greatest impact can be achieved if this first step
+is accepted in full.  In this case, the IO exception subhierarchy would
+become::
+
+    +-- IOError   (replacing OSError, WindowsError, EnvironmentError, etc.)
+        +-- io.BlockingIOError
+        +-- io.UnsupportedOperation (also inherits from ValueError)
+
+Justification
+-------------
+
+Not only does this first step present the user a simpler landscape as
+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]_.
+
+Exception attributes
+--------------------
+
+Coalescing WindowsError would mean the ``winerr`` 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
+by Python code.
 
 Deprecation of names
 --------------------
@@ -224,13 +255,15 @@
 challenges, especially where performance is important.
 
 
+.. _Step 2:
+
 Step 2: define additional subclasses
 ====================================
 
 The second step of the resolution is to extend the hierarchy by defining
 subclasses which will be raised, rather than their parent, for specific
 errno values.  Which errno values is subject to discussion, but a survey
-of existing exception matching practices (see **Appendix A**) helps us
+of existing exception matching practices (see `Appendix A`_) helps us
 propose a reasonable subset of all values.  Trying to map all errno
 mnemonics, indeed, seems foolish, pointless, and would pollute the root
 namespace.
@@ -246,7 +279,7 @@
 Prerequisite
 ------------
 
-Step 1 is a loose prerequisite for this.
+`Step 1`_ is a loose prerequisite for this.
 
 Prerequisite, because some errnos can currently be attached to different
 exception classes: for example, EBADF can be attached to both OSError and
@@ -304,13 +337,12 @@
   as a generic timeout exception, useful for other types of timeout (for
   example in Lock.acquire())
 
-This list assumes step 1 is accepted in full; the exception classes
+This list assumes `Step 1`_ is accepted in full; the exception classes
 described above would all derive from the now unified exception type
 OSError.  It will need reworking if a partial version of step 1 is accepted
 instead (again, see appendix A for the current distribution of errnos
 and exception types).
 
-
 Exception attributes
 --------------------
 
@@ -423,6 +455,8 @@
 etc.).
 
 
+.. _Appendix A:
+
 Appendix A: Survey of common errnos
 ===================================
 
@@ -504,6 +538,8 @@
 * ``EINTR``: interrupted function call
 
 
+.. _Appendix B:
+
 Appendix B: Survey of raised OS and IO errors
 =============================================
 
@@ -740,15 +776,27 @@
 zipimporter.get_data() can raise IOError.
 
 
+Acknowledgments
+===============
+
+Significant input has been received from Nick Coghlan.
+
 References
 ==========
 
-.. [1] "IO module precisions and exception hierarchy"
+.. [1] "IO module precisions and exception hierarchy":
    http://mail.python.org/pipermail/python-dev/2009-September/092130.html
 
-.. [2] Discussion of "Removing WindowsError" in PEP 348
+.. [2] Discussion of "Removing WindowsError" in PEP 348:
    http://www.python.org/dev/peps/pep-0348/#removing-windowserror
 
+.. [3] Google Code Search of ``IOError`` in Python code: `around 40000 results
+   <http://www.google.com/codesearch?q=lang%3Apython%20IOError>`_;
+   ``OSError``: `around 15200 results
+   <http://www.google.com/codesearch?q=lang%3Apython%20OSError>`_;
+   ``EnvironmentError``: `around 3000 results
+   <http://www.google.com/codesearch?q=lang%3Apython%20EnvironmentError>`_
+
 Copyright
 =========