This shows you the differences between the selected revision and the current version of the page.
| error_handling 2008/06/30 21:21 | error_handling 2008/07/09 09:23 current | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | ====== Handling errors ====== | ||
| - | =====Legacy Error Handling===== | + | As a plugin or core author, you might want to show error messages to the user. Doing so is very easy: |
| - | When an error occurs, two things should happen: | + | ''raise PyroomError('Here goes your error message')'' |
| - | * The user should be notified via a friendly message in the status line. This should signify a problem but should not contain a scary amount of detail. | + | |
| - | * If the "verbose" commandline switch has been used, a traceback or similar detailed error message should be printed to the terminal. | + | |
| - | ====Verbose Mode==== | + | The user will then see a dialog box with the value of the exception you just raised: |
| - | Verbose mode is set via the commandline switch "-v". If this switch is used, pyroom.py sets a variable called "verbose" to equal True. This variable should be passed through to any and all classes or methods which may wish to raise an error, so that they can decided whether or not to print a message to the terminal. | + | {{standard_error.png|}} |
| - | ==== Problems ==== | + | ===== When to raise exceptions ===== |
| - | * Error messages disappear when autosaving, switching buffers or anything else causes the status label to refresh | + | |
| - | * critical error messages don't get the user's attention when needed | + | |
| - | * current system of "raise, catch, print+status label" is somewhat tiresome | + | |
| - | * streamlined process of displaying error messages important for soon to come plugin system | + | |
| - | ===== New error handling ===== | + | One of PyRoom's goals is to be as distraction free as possible. You should avoid to raise exceptions of minor importance, just to notify the user of something. If there's an error and the user needs to know, go ahead and raise the exception. Breaking the user's workflow is a good thing at that point. |
| - | My proposed scheme of error handling allows developers to raise PyroomError from within core code or frome plugins, without having to catch it. PyroomError exceptions are caught on a global application level. In addition, any previously unhandeled exception is caught also. This creates two scenarios: | + | |
| - | * caught exception PyroomError: an error message is displayed to the user, in a dialog box. | + | If your code can go on and the user doesn't need to know about the error, you should be handling the error in the first place ;) |
| - | * caught an exception that was previously unhandeled: the user will be given some generic error message about the unhandeled exception being a program error and some "show details" switch, where the exception and a full traceback will be shown. Also, we might add a "report to launchpad"; button later | + | |
| - | ==== Rationale ==== | + | ===== Uncaught exceptions ===== |
| - | * raising dialog windows breaks the users' workflow, especially in a "distraction free editor" like pyroom is. This is intentional. If there's a problem, the user ought to know. E.g. when file saving fails. This shouldn't go unnoticed! | + | Uncaught exceptions should be considered programming errors and submitted to launchpad as bugs, where they can be fixed. Any uncaught exception will display another dialog, which allows the user to take a look at the traceback after clicking on a "details" button. |
| - | * errors that can go unnoticed don't need to be shown in the first place. Thus, no error messages in status bar | + | |
| - | * uncaught exceptions are programming errors, either because they should be caught or not be risen in the first place. Hence, the "bug report" dialog | + | {{uncaught_exception.png|}} |
| - | * ''raise PyroomError(_("Couldn't save file, insufficent permissions"))'' is easy | + | |
| - | * drop verbose mode, that's what debuggers are for, e.g. the excellent pdb (integrates into ipython, vim, emacs, etc) | + | ===== Technical details ===== |
| + | We're catching any previously uncaught exception, via an exception hook. Thus, exceptions no longer go to the terminal, pyroom has been started from (there might even be no such terminal). Handling exceptions via try/except works as expected, but anything that goes uncaught will be caught by our exception hook and displayed to the end user | ||
| + | |||
| + | ===== Retrieving details about errors ===== | ||
| + | Please don't use dialog boxes or print statements for this. Try the excellent python debugger. [[http://www.ferg.org/papers/debugging_in_python.html|Here's a HOWTO]] | ||