Update docs for configuration
[third_party/pep8] / 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 Features
11 --------
12
13 * Plugin architecture: Adding new checks is easy.
14
15 * Parseable output: Jump to error location in your editor.
16
17 * Small: Just one Python file, requires only stdlib. You can use just
18   the pep8.py file for this purpose.
19
20 * Comes with a comprehensive test suite.
21
22 Installation
23 ------------
24
25 You can install, upgrade, uninstall pep8.py with these commands::
26
27   $ pip install pep8
28   $ pip install --upgrade pep8
29   $ pip uninstall pep8
30
31 There's also a package for Debian/Ubuntu, but it's not always the
32 latest version.
33
34 Example usage and output
35 ------------------------
36
37 ::
38
39   $ pep8 --first 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/E40.py
53   testsuite/E40.py:2:10: E401 multiple imports on one line
54   import os, sys
55            ^
56       Imports should usually be on separate lines.
57
58       Okay: import os\nimport sys
59       E401: import sys, os
60
61
62 Or you can display how often each error was found::
63
64   $ pep8 --statistics -qq Python-2.5/Lib
65   232     E201 whitespace after '['
66   599     E202 whitespace before ')'
67   631     E203 whitespace before ','
68   842     E211 whitespace before '('
69   2531    E221 multiple spaces before operator
70   4473    E301 expected 1 blank line, found 0
71   4006    E302 expected 2 blank lines, found 1
72   165     E303 too many blank lines (4)
73   325     E401 multiple imports on one line
74   3615    E501 line too long (82 characters)
75   612     W601 .has_key() is deprecated, use 'in'
76   1188    W602 deprecated form of raising exception
77
78 Links
79 -----
80
81 .. image:: https://api.travis-ci.org/jcrocholl/pep8.png?branch=master
82    :target: https://travis-ci.org/jcrocholl/pep8
83    :alt: Build status
84
85 .. image:: https://pypip.in/wheel/pep8/badge.png?branch=master
86    :target: https://pypi.python.org/pypi/pep8
87    :alt: Wheel Status
88
89 * `Read the documentation <http://pep8.readthedocs.org/>`_
90
91 * `Fork me on GitHub <http://github.com/jcrocholl/pep8>`_