From 4d8faee55c0e49538379893455d55e9916164271 Mon Sep 17 00:00:00 2001
From: Antoine Pitrou <solipsis@pitrou.net>
Date: Fri, 3 Sep 2010 17:07:56 +0000
Subject: [PATCH] Add "Error" at the end of class names. Propose two new
 intermediate classes (ConnectionError and FileSystemError) Add a small
 diagram.

---
 pep-3151.txt | 72 +++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 52 insertions(+), 20 deletions(-)

diff --git a/pep-3151.txt b/pep-3151.txt
index 70ce046db..a7932d32e 100644
--- a/pep-3151.txt
+++ b/pep-3151.txt
@@ -154,7 +154,7 @@ something such as::
 
     try:
         os.remove(filename)
-    except FileNotFound:
+    except FileNotFoundError:
         pass
 
 
@@ -330,44 +330,76 @@ New exception classes
 The following tentative list of subclasses, along with a description and
 the list of errnos mapped to them, is submitted to discussion:
 
-* ``FileAlreadyExists``: trying to create a file or directory which already
-  exists (EEXIST)
+* ``FileAlreadyExistsError``: trying to create a file or directory which
+  already exists (EEXIST)
 
-* ``FileNotFound``: for all circumstances where a file and directory is
+* ``FileNotFoundError``: for all circumstances where a file and directory is
   requested but doesn't exist (ENOENT)
 
-* ``IsADirectory``: file-level operation (open(), os.remove()...) requested
-  on a directory (EISDIR)
+* ``IsADirectoryError``: file-level operation (open(), os.remove()...)
+  requested on a directory (EISDIR)
 
-* ``NotADirectory``: directory-level operation requested on something else
-  (ENOTDIR)
+* ``NotADirectoryError``: directory-level operation requested on something
+  else (ENOTDIR)
 
-* ``PermissionDenied``: trying to run an operation without the adequate access
-  rights - for example filesystem permissions (EACCESS, optionally EPERM)
+* ``PermissionError``: trying to run an operation without the adequate access
+  rights - for example filesystem permissions (EACCESS, EPERM)
 
 * ``BlockingIOError``: an operation would block on an object (e.g. socket) set
   for non-blocking operation (EAGAIN, EALREADY, EWOULDBLOCK, EINPROGRESS);
   this is the existing ``io.BlockingIOError`` with an extended role
 
-* ``BadFileDescriptor``: operation on an invalid file descriptor (EBADF);
+* ``FileDescriptorError``: operation on an invalid file descriptor (EBADF);
   the default error message could point out that most causes are that
   an existing file descriptor has been closed
 
-* ``ConnectionAborted``: connection attempt aborted by peer (ECONNABORTED)
+* ``ConnectionAbortedError``: connection attempt aborted by peer (ECONNABORTED)
 
-* ``ConnectionRefused``: connection reset by peer (ECONNREFUSED)
+* ``ConnectionRefusedError``: connection reset by peer (ECONNREFUSED)
 
-* ``ConnectionReset``: connection reset by peer (ECONNRESET)
+* ``ConnectionResetError``: connection reset by peer (ECONNRESET)
 
-* ``TimeoutError``: connection timed out (ECONNTIMEOUT); this could be re-cast
+* ``TimeoutError``: connection timed out (ECONNTIMEOUT); this can be re-cast
   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
-described above would all derive from the now unified exception type
-IOError.  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).
+In addition, the following exception class are proposed for inclusion:
+
+* ``ConnectionError``: a base class for ``ConnectionAbortedError``,
+  ``ConnectionRefusedError`` and ``ConnectionResetError``
+
+* ``FileSystemError``: a base class for ``FileAlreadyExistsError``,
+  ``FileNotFoundError``, ``IsADirectoryError`` and ``NotADirectoryError``
+
+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
+shown::
+
+    +-- BlockingIOError        EAGAIN, EALREADY, EWOULDBLOCK, EINPROGRESS
+    +-- ConnectionError
+        +-- ConnectionAbortedError                           ECONNABORTED
+        +-- ConnectionRefusedError                           ECONNREFUSED
+        +-- ConnectionResetError                               ECONNRESET
+    +-- FileDescriptorError                                         EBADF
+    +-- FileSystemError
+        +-- FileAlreadyExistsError                                 EEXIST
+        +-- FileNotFoundError                                      ENOENT
+        +-- IsADirectoryError                                      EISDIR
+        +-- NotADirectoryError                                    ENOTDIR
+    +-- PermissionError                                    EACCESS, EPERM
+    +-- TimeoutError                                         ECONNTIMEOUT
+
+Naming
+------
+
+Various naming controversies can arise.  One of them is whether all
+exception class names should end in "``Error``".  In favour is consistency
+with the rest of the exception hiearchy, against is concision (especially
+with long names such as ``FileAlreadyExistsError``).
+
+Another cosmetic issue is whether ``FileSystemError`` should be spelled
+``FilesystemError`` instead.
 
 Exception attributes
 --------------------