From c004fe89475420b0ecc38c4b083f02f54b86be9a Mon Sep 17 00:00:00 2001 From: Marc-Andre Lemburg Date: Fri, 2 Sep 2022 16:09:31 +0200 Subject: [PATCH 1/6] 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. --- pep-0249.txt | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/pep-0249.txt b/pep-0249.txt index 09d19dabc2f..1feaeaec71b 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`` [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`` [10]_. .. _InterfaceError: @@ -201,8 +201,8 @@ exceptions or subclasses thereof: This is the exception inheritance layout:: - StandardError - |__Warning + Exception [10]_ + |__Warning [11]_ |__Error |__InterfaceError |__DatabaseError @@ -731,14 +731,12 @@ Implementation Hints for Module Authors constructor. * Here is a snippet of Python code that implements the exception - hierarchy defined above:: + hierarchy defined above [10]_:: - import exceptions - - class Error(exceptions.StandardError): + class Error(Exception): pass - class Warning(exceptions.StandardError): + class Warning(Exception): pass class InterfaceError(Error): @@ -1297,6 +1295,23 @@ Footnotes ``WHERE`` clause, or clearly document a different interpretation of the ``.rowcount`` attribute. +.. [10] In Python 2 and earlier versions of this PEP, + ``exceptions.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.Exception`` as base class instead. Both + ``StandardError`` and ``Exception`` are available as builtin + objects, so it is not necessary to import the ``exceptions`` module + for this. 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, the warning framework in + Python had not yet existed. + Acknowledgements ================ From 67bbfebb4a212204dd11551bf8dad1284c833d5e Mon Sep 17 00:00:00 2001 From: Marc-Andre Lemburg Date: Fri, 2 Sep 2022 16:18:14 +0200 Subject: [PATCH 2/6] Fix typo and add year for more context. --- pep-0249.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep-0249.txt b/pep-0249.txt index 1feaeaec71b..8c9a624bfa5 100644 --- a/pep-0249.txt +++ b/pep-0249.txt @@ -1309,8 +1309,8 @@ Footnotes .. [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, the warning framework in - Python had not yet existed. + the time of writing of the DB-API 2.0 in 1999, the warning framework + in Python had not yet existed. Acknowledgements From 5e5522f4e58d731de565ec6368dcd507c5751b72 Mon Sep 17 00:00:00 2001 From: Marc-Andre Lemburg Date: Fri, 2 Sep 2022 17:58:13 +0200 Subject: [PATCH 3/6] 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. --- pep-0249.txt | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/pep-0249.txt b/pep-0249.txt index 8c9a624bfa5..9b834b3f910 100644 --- a/pep-0249.txt +++ b/pep-0249.txt @@ -1295,17 +1295,16 @@ Footnotes ``WHERE`` clause, or clearly document a different interpretation of the ``.rowcount`` attribute. -.. [10] In Python 2 and earlier versions of this PEP, - ``exceptions.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.Exception`` as base class instead. Both - ``StandardError`` and ``Exception`` are available as builtin - objects, so it is not necessary to import the ``exceptions`` module - for this. 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. +.. [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. + Both ``StandardError`` and ``Exception`` are available as builtin + exception objects. 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 From b4c4c3bb8c49ba968d77908e5e68966bf888916f Mon Sep 17 00:00:00 2001 From: Marc-Andre Lemburg Date: Fri, 2 Sep 2022 19:33:02 +0200 Subject: [PATCH 4/6] 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. --- pep-0249.txt | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/pep-0249.txt b/pep-0249.txt index 9b834b3f910..e8e61b14beb 100644 --- a/pep-0249.txt +++ b/pep-0249.txt @@ -1299,12 +1299,10 @@ Footnotes 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. - Both ``StandardError`` and ``Exception`` are available as builtin - exception objects. 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. + 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 From c49fdd44f03dbb73022f96eebffdd740aba6ae18 Mon Sep 17 00:00:00 2001 From: Marc-Andre Lemburg Date: Tue, 6 Sep 2022 15:45:28 +0200 Subject: [PATCH 5/6] Grammar fix --- pep-0249.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep-0249.txt b/pep-0249.txt index e8e61b14beb..60418ea79ac 100644 --- a/pep-0249.txt +++ b/pep-0249.txt @@ -1307,7 +1307,7 @@ Footnotes .. [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 had not yet existed. + in Python did not yet exist. Acknowledgements From f0bf65b568c76acb329fd7b1210256ea8a55abb7 Mon Sep 17 00:00:00 2001 From: Marc-Andre Lemburg Date: Tue, 6 Sep 2022 16:42:01 +0200 Subject: [PATCH 6/6] Fix exception hierarchy formatting --- pep-0249.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/pep-0249.txt b/pep-0249.txt index 60418ea79ac..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 - ``Exception`` [10]_ [11]_. + ``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 ``Exception`` [10]_. + Python ``Exception`` class [10]_. .. _InterfaceError: @@ -199,10 +199,12 @@ 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]_: - Exception [10]_ - |__Warning [11]_ +.. code-block:: text + + Exception + |__Warning |__Error |__InterfaceError |__DatabaseError