third_party/pep8/docs/developer.rst

   1 .. currentmodule:: pep8
   2
   3 =================
   4 Developer's notes
   5 =================
   6
   7
   8 Source code
   9 ~~~~~~~~~~~
  10
  11 The source code is currently `available on GitHub`_ under the terms and
  12 conditions of the :ref:`Expat license <license>`.  Fork away!
  13
  14 * `Source code <https://github.com/jcrocholl/pep8>`_ and
  15   `issue tracker <https://github.com/jcrocholl/pep8/issues>`_ on GitHub.
  16 * `Continuous tests <http://travis-ci.org/jcrocholl/pep8>`_ against Python
  17   2.6 through 3.4 and PyPy, on `Travis-CI platform
  18   <http://about.travis-ci.org/>`_.
  19
  20 .. _available on GitHub: https://github.com/jcrocholl/pep8
  21
  22
  23 Contribute
  24 ~~~~~~~~~~
  25
  26 You can add checks to this program by writing plugins.  Each plugin is
  27 a simple function that is called for each line of source code, either
  28 physical or logical.
  29
  30 Physical line:
  31
  32 * Raw line of text from the input file.
  33
  34 Logical line:
  35
  36 * Multi-line statements converted to a single line.
  37 * Stripped left and right.
  38 * Contents of strings replaced with ``"xxx"`` of same length.
  39 * Comments removed.
  40
  41 The check function requests physical or logical lines by the name of
  42 the first argument::
  43
  44   def maximum_line_length(physical_line)
  45   def extraneous_whitespace(logical_line)
  46   def blank_lines(logical_line, blank_lines, indent_level, line_number)
  47
  48 The last example above demonstrates how check plugins can request
  49 additional information with extra arguments.  All attributes of the
  50 :class:`Checker` object are available.  Some examples:
  51
  52 * ``lines``: a list of the raw lines from the input file
  53 * ``tokens``: the tokens that contribute to this logical line
  54 * ``line_number``: line number in the input file
  55 * ``total_lines``: number of lines in the input file
  56 * ``blank_lines``: blank lines before this one
  57 * ``indent_char``: indentation character in this file (``" "`` or ``"\t"``)
  58 * ``indent_level``: indentation (with tabs expanded to multiples of 8)
  59 * ``previous_indent_level``: indentation on previous line
  60 * ``previous_logical``: previous logical line
  61
  62 Check plugins can also maintain per-file state. If you need this, declare
  63 a parameter named ``checker_state``. You will be passed a dict, which will be
  64 the same one for all lines in the same file but a different one for different
  65 files. Each check plugin gets its own dict, so you don't need to worry about
  66 clobbering the state of other plugins.
  67
  68 The docstring of each check function shall be the relevant part of
  69 text from `PEP 8`_.  It is printed if the user enables ``--show-pep8``.
  70 Several docstrings contain examples directly from the `PEP 8`_ document.
  71
  72 ::
  73
  74   Okay: spam(ham[1], {eggs: 2})
  75   E201: spam( ham[1], {eggs: 2})
  76
  77 These examples are verified automatically when pep8.py is run with the
  78 ``--doctest`` option.  You can add examples for your own check functions.
  79 The format is simple: ``"Okay"`` or error/warning code followed by colon
  80 and space, the rest of the line is example source code.  If you put ``'r'``
  81 before the docstring, you can use ``\n`` for newline and ``\t`` for tab.
  82
  83 Then be sure to pass the tests::
  84
  85   $ python pep8.py --testsuite testsuite
  86   $ python pep8.py --doctest
  87   $ python pep8.py --verbose pep8.py
  88
  89 .. _PEP 8: http://www.python.org/dev/peps/pep-0008/
  90
  91
  92 Changes
  93 ~~~~~~~
  94
  95 .. include:: ../CHANGES.txt
  96    :start-line: 3