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   try:
  47       ...
  48   except ... as ex:
  49       add_ex_tb(ex)
  50       pending_ex = ex
  51   ...
  52   raise pending_ex
  53
  54 When an exception is thrown from an exception handler, the pending
  55 exception should be the `"context"
  56 <https://docs.python.org/3/reference/simple_stmts.html#the-raise-statement>`_
  57 of the new exception, which can be accomplished (portably) via
  58 ``pending_raise()``::
  59
  60   try:
  61       ...
  62   except ... as ex:
  63       with pending_raise(ex):
  64           clean_up()
  65
  66 This should do roughly the same thing in Python 2 and Python 3,
  67 throwing any exception from ``clean_up()`` after adding ex as the
  68 ``__context__`` if clean_up() throws, and throwing ``ex`` otherwise.
  69
  70 If for some reason, you need more control, you can use
  71 ``add_ex_ctx()`` directly::
  72
  73   try:
  74       ...
  75   except ... as ex:
  76       add_ex_tb(ex)
  77       try:
  78           ...
  79       except ... as ex2:
  80           add_ex_tb(ex2)
  81           raise add_ex_ctx(ex2, ex)
  82       raise
  83
  84 See the end of ``lib/bup/compat.py`` for a functional example, and all
  85 of this can be removed once we drop support for Python 2.