doc: move all sources to the same directory
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
This commit is contained in:
parent
bbc84ead0f
commit
d5cea50370
@ -1,51 +0,0 @@
|
|||||||
.. -*- 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.
|
|
@ -1 +0,0 @@
|
|||||||
../CodingGuidelines.rst
|
|
51
docs/doc-src/CodingGuidelines.rst
Normal file
51
docs/doc-src/CodingGuidelines.rst
Normal file
@ -0,0 +1,51 @@
|
|||||||
|
.. -*- 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.
|
Loading…
Reference in New Issue
Block a user