forked from OfflineIMAP/offlineimap
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Properly re-raise exception to save original tracebacks
We usually mutate some exceptions to OfflineImapError() and it is a whole lot better if such exception will show up with the original traceback, so all valid occurrences of such mutations were transformed to the 3-tuple form of "raise". Had also added coding guidelines document where this re-raise strategy is documented. Signed-off-by: Eygene Ryabinkin <rea@codelabs.ru>
- Loading branch information
Showing
15 changed files
with
150 additions
and
26 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,102 @@ | ||
.. -*- coding: utf-8 -*- | ||
.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap | ||
.. _OLI_git_repo: git://github.com/OfflineIMAP/offlineimap.git | ||
|
||
================================= | ||
Coding guidelines for OfflineIMAP | ||
================================= | ||
|
||
.. contents:: | ||
.. .. sectnum:: | ||
|
||
This document contains assorted guidelines for programmers that want | ||
to hack OfflineIMAP. | ||
|
||
|
||
------------------ | ||
Exception handling | ||
------------------ | ||
|
||
OfflineIMAP on many occasions re-raises various exceptions and often | ||
changes exception type to `OfflineImapError`. This is not a problem | ||
per se, but you must always remember that we need to preserve original | ||
tracebacks. This is not hard if you follow these simple rules. | ||
|
||
For re-raising original exceptions, just use:: | ||
|
||
raise | ||
|
||
from inside your exception handling code. | ||
|
||
If you need to change exception type, or its argument, or whatever, | ||
use this three-argument form:: | ||
|
||
raise YourExceptionClass(argum, ents), None, sys.exc_info()[2] | ||
|
||
In this form, you're creating an instance of new exception, so ``raise`` | ||
will deduce its ``type`` and ``value`` parameters from the first argument, | ||
thus the second expression passed to ``raise`` is always ``None``. | ||
And the third one is the traceback object obtained from the thread-safe | ||
``exc_info()`` function. | ||
|
||
In fact, if you hadn't already imported the whole ``sys`` module, it will | ||
be better to import just ``exc_info()``:: | ||
|
||
from sys import exc_info | ||
|
||
and raise like this:: | ||
|
||
raise YourExceptionClass(argum, ents), None, exc_info()[2] | ||
|
||
since this is the historically-preferred style in the OfflineIMAP code. | ||
.. -*- coding: utf-8 -*- | ||
.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap | ||
.. _OLI_git_repo: git://github.com/OfflineIMAP/offlineimap.git | ||
|
||
================================= | ||
Coding guidelines for OfflineIMAP | ||
================================= | ||
|
||
.. contents:: | ||
.. .. sectnum:: | ||
|
||
This document contains assorted guidelines for programmers that want | ||
to hack OfflineIMAP. | ||
|
||
|
||
------------------ | ||
Exception handling | ||
------------------ | ||
|
||
OfflineIMAP on many occasions re-raises various exceptions and often | ||
changes exception type to `OfflineImapError`. This is not a problem | ||
per se, but you must always remember that we need to preserve original | ||
tracebacks. This is not hard if you follow these simple rules. | ||
|
||
For re-raising original exceptions, just use:: | ||
|
||
raise | ||
|
||
from inside your exception handling code. | ||
|
||
If you need to change exception type, or its argument, or whatever, | ||
use this three-argument form:: | ||
|
||
raise YourExceptionClass(argum, ents), None, sys.exc_info()[2] | ||
|
||
In this form, you're creating an instance of new exception, so ``raise`` | ||
will deduce its ``type`` and ``value`` parameters from the first argument, | ||
thus the second expression passed to ``raise`` is always ``None``. | ||
And the third one is the traceback object obtained from the thread-safe | ||
``exc_info()`` function. | ||
|
||
In fact, if you hadn't already imported the whole ``sys`` module, it will | ||
be better to import just ``exc_info()``:: | ||
|
||
from sys import exc_info | ||
|
||
and raise like this:: | ||
|
||
raise YourExceptionClass(argum, ents), None, exc_info()[2] | ||
|
||
since this is the historically-preferred style in the OfflineIMAP code. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
../CodingGuidelines.rst |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.