git.samba.org - third_party/pep8/blob - README.rst

   1 pep8 - Python style guide checker
   2 =================================
   3
   4 pep8 is a tool to check your Python code against some of the style conventions
   5 in `PEP 8`_.
   6
   7 .. _PEP 8: http://www.python.org/dev/peps/pep-0008/
   8
   9
  10 Mailing List
  11 ------------
  12 http://groups.google.com/group/pep8
  13
  14
  15 Features
  16 --------
  17
  18 * Plugin architecture: Adding new checks is easy.
  19
  20 * Parseable output: Jump to error location in your editor.
  21
  22 * Small: Just one Python file, requires only stdlib.  You can use just the
  23   pep8.py file for this purpose.
  24
  25 * Easy_installable, of course!
  26
  27
  28 Installation
  29 ------------
  30
  31 Just an ``easy_install pep8`` ought to do the trick.
  32
  33
  34 Example usage and output
  35 ------------------------
  36
  37 ::
  38
  39   $ pep8 optparse.py
  40   optparse.py:69:11: E401 multiple imports on one line
  41   optparse.py:77:1: E302 expected 2 blank lines, found 1
  42   optparse.py:88:5: E301 expected 1 blank line, found 0
  43   optparse.py:222:34: W602 deprecated form of raising exception
  44   optparse.py:347:31: E211 whitespace before '('
  45   optparse.py:357:17: E201 whitespace after '{'
  46   optparse.py:472:29: E221 multiple spaces before operator
  47   optparse.py:544:21: W601 .has_key() is deprecated, use 'in'
  48
  49 You can also make pep8.py show the source code for each error, and
  50 even the relevant text from PEP 8::
  51
  52   $ pep8 --show-source --show-pep8 testsuite/E111.py
  53   testsuite/E111.py:2:3: E111 indentation is not a multiple of four
  54     print x
  55     ^
  56       Use 4 spaces per indentation level.
  57
  58       For really old code that you don't want to mess up, you can
  59       continue to use 8-space tabs.
  60
  61 Or you can display how often each error was found::
  62
  63   $ pep8 --statistics -qq --filename=*.py Python-2.5/Lib
  64   232     E201 whitespace after '['
  65   599     E202 whitespace before ')'
  66   631     E203 whitespace before ','
  67   842     E211 whitespace before '('
  68   2531    E221 multiple spaces before operator
  69   4473    E301 expected 1 blank line, found 0
  70   4006    E302 expected 2 blank lines, found 1
  71   165     E303 too many blank lines (4)
  72   325     E401 multiple imports on one line
  73   3615    E501 line too long (82 characters)
  74   612     W601 .has_key() is deprecated, use 'in'
  75   1188    W602 deprecated form of raising exception
  76
  77 Quick help is available on the command line::
  78
  79   $ pep8 -h
  80   Usage: pep8.py [options] input ...
  81
  82   Options:
  83     --version            show program's version number and exit
  84     -h, --help           show this help message and exit
  85     -v, --verbose        print status messages, or debug with -vv
  86     -q, --quiet          report only file names, or nothing with -qq
  87     -r, --repeat         show all occurrences of the same error
  88     --exclude=patterns   exclude files or directories which match these comma
  89                          separated patterns (default: .svn,CVS,.bzr,.hg,.git)
  90     --filename=patterns  when parsing directories, only check filenames matching
  91                          these comma separated patterns (default: *.py)
  92     --select=errors      select errors and warnings (e.g. E,W6)
  93     --ignore=errors      skip errors and warnings (e.g. E4,W)
  94     --show-source        show source code for each error
  95     --show-pep8          show text of PEP 8 for each error
  96     --statistics         count errors and warnings
  97     --count              count total number of errors and warnings
  98     --benchmark          measure processing speed
  99     --testsuite=dir      run regression tests from dir
 100     --doctest            run doctest on myself
 101
 102 Feedback
 103 --------
 104
 105 Your feedback is more than welcome. Write email to
 106 johann@rocholl.net or post bugs and feature requests on github:
 107
 108 http://github.com/jcrocholl/pep8/issues
 109
 110 Source download
 111 ---------------
 112
 113 The source code is currently available on github. Fork away!
 114
 115 http://github.com/jcrocholl/pep8/