CODINGSTYLE

   1 .. -*-rst-*-
   2
   3 C
   4 =
   5
   6 The C implementations should follow the `kernel/git coding style
   7 <http://www.kernel.org/doc/Documentation/CodingStyle>`_.
   8
   9
  10 Python
  11 ======
  12
  13 Python code follows `PEP8 <http://www.python.org/dev/peps/pep-0008/>`_
  14 with regard to coding style and `PEP257
  15 <http://www.python.org/dev/peps/pep-0257/>`_ with regard to docstring
  16 style. Multi-line docstrings should have one short summary line,
  17 followed by a blank line and a series of paragraphs. The last
  18 paragraph should be followed by a line that closes the docstring (no
  19 blank line in between). Here's an example from
  20 ``lib/bup/helpers.py``::
  21
  22   def unlink(f):
  23       """Delete a file at path 'f' if it currently exists.
  24
  25       Unlike os.unlink(), does not throw an exception if the file didn't already
  26       exist.
  27       """
  28       ...
  29
  30 Module-level docstrings follow exactly the same guidelines but without the
  31 blank line between the summary and the details.
  32
  33
  34 Exception Handling
  35 ------------------
  36
  37 Avoid finally: blocks in favor of explict catches because a throw
  38 from a finally block will lose any pending exception.  An explicit
  39 catch can chain it (see below).
  40
  41 To behave similarly under Python 2 and 3, use add_ex_tb() to
  42 explicitly add stack traces to any exceptions that are going to be
  43 re-raised by anything other than a no-argument raise (otherwise the
  44 stack trace will be lost)::
  45
  46
  47   try:
  48       ...
  49   except ... as ex:
  50       add_ex_tb(ex)
  51       pending_ex = ex
  52   ...
  53   raise pending_ex
  54
  55 If an exception is thrown from an exception handler, the pending
  56 exception should be the `"context"
  57 <https://docs.python.org/3/reference/simple_stmts.html#the-raise-statement>`_
  58 of the new exception This can be accomplished via
  59 ``add_ex_ctx()``::
  60
  61   try:
  62       ...
  63   except ... as ex:
  64       add_ex_tb(ex)
  65       try:
  66           ...
  67       except ... as ex2:
  68           add_ex_tb(ex2)
  69           raise add_ex_ctx(ex2, ex)
  70
  71 See the end of ``lib/bup/compat.py`` for a functional example.