From 77039588fffa7db88a1745aa153e8de7c882bc1e Mon Sep 17 00:00:00 2001
From: Marc-Andre Lemburg <mal@egenix.com>
Date: Tue, 6 Sep 2022 16:49:53 +0200
Subject: [PATCH] PEP 249: Replace StandardError with Exception (#2781)

* Replace StandardError with Exception to avoid confusion when using
the DB-API 2.0 in the context of Python 3.

Add a note about a future upgrade to the Warning base class.

Fixes #2776.

* Fix typo and add year for more context.

* Remove mention of the exceptions module

This was removed in Python 3 as well.  Python 2.7 doesn't need it either,
since all standard exceptions are builtin objects.

* Remove mention of exception objects being builtins.

They were already for a very long time, so this is pointless.
I only had this sentence to explain why I had removed the
"import exceptions" line from the Python 2 days.

* Grammar fix

* Fix exception hierarchy formatting
---
 pep-0249.txt | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/pep-0249.txt b/pep-0249.txt
index 09d19dabc2f..011486cf16d 100644
--- a/pep-0249.txt
+++ b/pep-0249.txt
@@ -118,7 +118,7 @@ exceptions or subclasses thereof:
 `Warning`_
     Exception raised for important warnings like data truncations
     while inserting, etc. It must be a subclass of the Python
-    ``StandardError`` (defined in the module exceptions).
+    ``Exception`` class [10]_ [11]_.
 
 
 .. _Error:
@@ -128,7 +128,7 @@ exceptions or subclasses thereof:
     exceptions. You can use this to catch all errors with one single
     ``except`` statement. Warnings are not considered errors and thus
     should not use this class as base. It must be a subclass of the
-    Python ``StandardError`` (defined in the module exceptions).
+    Python ``Exception`` class [10]_.
 
 
 .. _InterfaceError:
@@ -199,9 +199,11 @@ exceptions or subclasses thereof:
     or has transactions turned off.  It must be a subclass of
     DatabaseError_.
 
-This is the exception inheritance layout::
+This is the exception inheritance layout [10]_ [11]_:
 
-    StandardError
+.. code-block:: text
+
+    Exception
     |__Warning
     |__Error
        |__InterfaceError
@@ -731,14 +733,12 @@ Implementation Hints for Module Authors
   constructor.
 
 * Here is a snippet of Python code that implements the exception
-  hierarchy defined above::
-
-        import exceptions
+  hierarchy defined above [10]_::
 
-        class Error(exceptions.StandardError):
+        class Error(Exception):
             pass
 
-        class Warning(exceptions.StandardError):
+        class Warning(Exception):
             pass
 
         class InterfaceError(Error):
@@ -1297,6 +1297,20 @@ Footnotes
     ``WHERE`` clause, or clearly document a different interpretation
     of the ``.rowcount`` attribute.
 
+.. [10] In Python 2 and earlier versions of this PEP, ``StandardError``
+    was used as the base class for all DB-API exceptions. Since
+    ``StandardError`` was removed in Python 3, database modules
+    targeting Python 3 should use ``Exception`` as base class instead.
+    The PEP was updated to use ``Exception`` throughout the text, to
+    avoid confusion. The change should not affect existing modules or
+    uses of those modules, since all DB-API error exception classes are
+    still rooted at the ``Error`` or ``Warning`` classes.
+
+.. [11] In a future revision of the DB-API, the base class for
+    ``Warning`` will likely change to the builtin ``Warning`` class. At
+    the time of writing of the DB-API 2.0 in 1999, the warning framework
+    in Python did not yet exist.
+
 
 Acknowledgements
 ================