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
   5 conventions 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
  23   the pep8.py file for this purpose.
  24
  25 * Comes with a comprehensive test suite.
  26
  27 Installation
  28 ------------
  29
  30 You can install, upgrade, uninstall pep8.py with these commands::
  31
  32   $ sudo pip install pep8
  33   $ sudo pip install --upgrade pep8
  34   $ sudo pip uninstall pep8
  35
  36 Or if you don't have `pip`::
  37
  38   $ sudo easy_install pep8
  39
  40 There's also a package for Debian/Ubuntu, but it's not always the
  41 latest version::
  42
  43   $ sudo apt-get install pep8
  44
  45 Example usage and output
  46 ------------------------
  47
  48 ::
  49
  50   $ pep8 --first optparse.py
  51   optparse.py:69:11: E401 multiple imports on one line
  52   optparse.py:77:1: E302 expected 2 blank lines, found 1
  53   optparse.py:88:5: E301 expected 1 blank line, found 0
  54   optparse.py:222:34: W602 deprecated form of raising exception
  55   optparse.py:347:31: E211 whitespace before '('
  56   optparse.py:357:17: E201 whitespace after '{'
  57   optparse.py:472:29: E221 multiple spaces before operator
  58   optparse.py:544:21: W601 .has_key() is deprecated, use 'in'
  59
  60 You can also make pep8.py show the source code for each error, and
  61 even the relevant text from PEP 8::
  62
  63   $ pep8 --show-source --show-pep8 testsuite/E40.py
  64   testsuite/E40.py:2:10: E401 multiple imports on one line
  65   import os, sys
  66            ^
  67       Imports should usually be on separate lines.
  68
  69       Okay: import os\nimport sys
  70       E401: import sys, os
  71
  72
  73 Or you can display how often each error was found::
  74
  75   $ pep8 --statistics -qq Python-2.5/Lib
  76   232     E201 whitespace after '['
  77   599     E202 whitespace before ')'
  78   631     E203 whitespace before ','
  79   842     E211 whitespace before '('
  80   2531    E221 multiple spaces before operator
  81   4473    E301 expected 1 blank line, found 0
  82   4006    E302 expected 2 blank lines, found 1
  83   165     E303 too many blank lines (4)
  84   325     E401 multiple imports on one line
  85   3615    E501 line too long (82 characters)
  86   612     W601 .has_key() is deprecated, use 'in'
  87   1188    W602 deprecated form of raising exception
  88
  89 Quick help is available on the command line::
  90
  91   $ pep8 -h
  92   Usage: pep8.py [options] input ...
  93
  94   Options:
  95     --version            show program's version number and exit
  96     -h, --help           show this help message and exit
  97     -v, --verbose        print status messages, or debug with -vv
  98     -q, --quiet          report only file names, or nothing with -qq
  99     -r, --repeat         (obsolete) show all occurrences of the same error
 100     --first              show first occurrence of each error
 101     --exclude=patterns   exclude files or directories which match these comma
 102                          separated patterns (default: .svn,CVS,.bzr,.hg,.git)
 103     --filename=patterns  when parsing directories, only check filenames matching
 104                          these comma separated patterns (default: *.py)
 105     --select=errors      select errors and warnings (e.g. E,W6)
 106     --ignore=errors      skip errors and warnings (e.g. E4,W)
 107     --show-source        show source code for each error
 108     --show-pep8          show text of PEP 8 for each error (implies --first)
 109     --statistics         count errors and warnings
 110     --count              print total number of errors and warnings to standard
 111                          error and set exit code to 1 if total is not null
 112     --benchmark          measure processing speed
 113     --testsuite=dir      run regression tests from dir
 114     --max-line-length=n  set maximum allowed line length (default: 79)
 115     --doctest            run doctest on myself
 116     --config=path        config file location (default: /home/user/.config/pep8)
 117     --format=format      set the error format [default|pylint|<custom>]
 118
 119 Feedback
 120 --------
 121
 122 Your feedback is more than welcome. Write email to
 123 johann@rocholl.net or post bugs and feature requests on github:
 124
 125 http://github.com/jcrocholl/pep8/issues
 126
 127 Source download
 128 ---------------
 129
 130 .. image:: https://secure.travis-ci.org/jcrocholl/pep8.png?branch=master
 131    :target: https://secure.travis-ci.org/jcrocholl/pep8
 132    :alt: Build status
 133
 134 The source code is currently available on github. Fork away!
 135
 136 http://github.com/jcrocholl/pep8/