<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Introduction — pep8 1.5.7 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: './', VERSION: '1.5.7', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="top" title="pep8 1.5.7 documentation" href="index.html" /> <link rel="next" title="Advanced usage" href="advanced.html" /> <link rel="prev" title="pep8’s documentation" href="index.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="advanced.html" title="Advanced usage" accesskey="N">next</a> |</li> <li class="right" > <a href="index.html" title="pep8’s documentation" accesskey="P">previous</a> |</li> <li><a href="index.html">pep8 1.5.7 documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="introduction"> <h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1> <p>pep8 is a tool to check your Python code against some of the style conventions in <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP 8</a>.</p> <div class="contents local topic" id="contents"> <ul class="simple"> <li><a class="reference internal" href="#features" id="id2">Features</a></li> <li><a class="reference internal" href="#disclaimer" id="id3">Disclaimer</a></li> <li><a class="reference internal" href="#installation" id="id4">Installation</a></li> <li><a class="reference internal" href="#example-usage-and-output" id="id5">Example usage and output</a></li> <li><a class="reference internal" href="#configuration" id="id6">Configuration</a></li> <li><a class="reference internal" href="#error-codes" id="id7">Error codes</a></li> <li><a class="reference internal" href="#related-tools" id="id8">Related tools</a></li> </ul> </div> <div class="section" id="features"> <h2><a class="toc-backref" href="#id2">Features</a><a class="headerlink" href="#features" title="Permalink to this headline">¶</a></h2> <ul class="simple"> <li>Plugin architecture: Adding new checks is easy.</li> <li>Parseable output: Jump to error location in your editor.</li> <li>Small: Just one Python file, requires only stdlib. You can use just the pep8.py file for this purpose.</li> <li>Comes with a comprehensive test suite.</li> </ul> </div> <div class="section" id="disclaimer"> <h2><a class="toc-backref" href="#id3">Disclaimer</a><a class="headerlink" href="#disclaimer" title="Permalink to this headline">¶</a></h2> <p>This utility does not enforce every single rule of PEP 8. It helps to verify that some coding conventions are applied but it does not intend to be exhaustive. Some rules cannot be expressed with a simple algorithm, and other rules are only guidelines which you could circumvent when you need to.</p> <p>Always remember this statement from <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP 8</a>:</p> <blockquote> <div><em>A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important.</em></div></blockquote> <p>Among other things, these features are currently not in the scope of the <tt class="docutils literal"><span class="pre">pep8</span></tt> library:</p> <ul class="simple"> <li><strong>naming conventions</strong>: this kind of feature is supported through plugins. Install <a class="reference external" href="https://pypi.python.org/pypi/flake8">flake8</a> and the <a class="reference external" href="https://pypi.python.org/pypi/pep8-naming">pep8-naming extension</a> to use this feature.</li> <li><strong>docstring conventions</strong>: they are not in the scope of this library; see the <a class="reference external" href="https://github.com/GreenSteam/pep257">pep257 project</a>.</li> <li><strong>automatic fixing</strong>: see the section <em>PEP8 Fixers</em> in the <a class="reference internal" href="#related-tools"><em>related tools</em></a> page.</li> </ul> </div> <div class="section" id="installation"> <h2><a class="toc-backref" href="#id4">Installation</a><a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2> <p>You can install, upgrade, uninstall pep8.py with these commands:</p> <div class="highlight-python"><div class="highlight"><pre>$ pip install pep8 $ pip install --upgrade pep8 $ pip uninstall pep8 </pre></div> </div> <p>There’s also a package for Debian/Ubuntu, but it’s not always the latest version:</p> <div class="highlight-python"><div class="highlight"><pre>$ sudo apt-get install pep8 </pre></div> </div> </div> <div class="section" id="example-usage-and-output"> <h2><a class="toc-backref" href="#id5">Example usage and output</a><a class="headerlink" href="#example-usage-and-output" title="Permalink to this headline">¶</a></h2> <div class="highlight-python"><div class="highlight"><pre>$ pep8 --first optparse.py optparse.py:69:11: E401 multiple imports on one line optparse.py:77:1: E302 expected 2 blank lines, found 1 optparse.py:88:5: E301 expected 1 blank line, found 0 optparse.py:222:34: W602 deprecated form of raising exception optparse.py:347:31: E211 whitespace before '(' optparse.py:357:17: E201 whitespace after '{' optparse.py:472:29: E221 multiple spaces before operator optparse.py:544:21: W601 .has_key() is deprecated, use 'in' </pre></div> </div> <p>You can also make pep8.py show the source code for each error, and even the relevant text from PEP 8:</p> <div class="highlight-python"><div class="highlight"><pre>$ pep8 --show-source --show-pep8 testsuite/E40.py testsuite/E40.py:2:10: E401 multiple imports on one line import os, sys ^ Imports should usually be on separate lines. Okay: import os\nimport sys E401: import sys, os </pre></div> </div> <p>Or you can display how often each error was found:</p> <div class="highlight-python"><div class="highlight"><pre>$ pep8 --statistics -qq Python-2.5/Lib 232 E201 whitespace after '[' 599 E202 whitespace before ')' 631 E203 whitespace before ',' 842 E211 whitespace before '(' 2531 E221 multiple spaces before operator 4473 E301 expected 1 blank line, found 0 4006 E302 expected 2 blank lines, found 1 165 E303 too many blank lines (4) 325 E401 multiple imports on one line 3615 E501 line too long (82 characters) 612 W601 .has_key() is deprecated, use 'in' 1188 W602 deprecated form of raising exception </pre></div> </div> <p>Quick help is available on the command line:</p> <div class="highlight-python"><div class="highlight"><pre>$ pep8 -h Usage: pep8 [options] input ... Options: --version show program's version number and exit -h, --help show this help message and exit -v, --verbose print status messages, or debug with -vv -q, --quiet report only file names, or nothing with -qq --first show first occurrence of each error --exclude=patterns exclude files or directories which match these comma separated patterns (default: .svn,CVS,.bzr,.hg,.git) --filename=patterns when parsing directories, only check filenames matching these comma separated patterns (default: *.py) --select=errors select errors and warnings (e.g. E,W6) --ignore=errors skip errors and warnings (e.g. E4,W) --show-source show source code for each error --show-pep8 show text of PEP 8 for each error (implies --first) --statistics count errors and warnings --count print total number of errors and warnings to standard error and set exit code to 1 if total is not null --max-line-length=n set maximum allowed line length (default: 79) --hang-closing hang closing bracket instead of matching indentation of opening bracket's line --format=format set the error format [default|pylint|<custom>] --diff report only lines changed according to the unified diff received on STDIN Testing Options: --benchmark measure processing speed Configuration: The project options are read from the [pep8] section of the tox.ini file or the setup.cfg file located in any parent folder of the path(s) being processed. Allowed options are: exclude, filename, select, ignore, max-line-length, hang-closing, count, format, quiet, show-pep8, show-source, statistics, verbose. --config=path user config file location (default: ~/.config/pep8) </pre></div> </div> </div> <div class="section" id="configuration"> <h2><a class="toc-backref" href="#id6">Configuration</a><a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2> <p>The behaviour may be configured at two levels.</p> <p>The user settings are read from the <tt class="docutils literal"><span class="pre">~/.config/pep8</span></tt> file and for Windows from the <tt class="docutils literal"><span class="pre">~\.pep8</span></tt> file. Example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">pep8</span><span class="p">]</span> <span class="n">ignore</span> <span class="o">=</span> <span class="n">E226</span><span class="p">,</span><span class="n">E302</span><span class="p">,</span><span class="n">E41</span> <span class="nb">max</span><span class="o">-</span><span class="n">line</span><span class="o">-</span><span class="n">length</span> <span class="o">=</span> <span class="mi">160</span> </pre></div> </div> <p>At the project level, a <tt class="docutils literal"><span class="pre">tox.ini</span></tt> file or a <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> file is read if present (<tt class="docutils literal"><span class="pre">.pep8</span></tt> file is also supported, but it is deprecated). If none of these files have a <tt class="docutils literal"><span class="pre">[pep8]</span></tt> section, no project specific configuration is loaded.</p> <p>If the <tt class="docutils literal"><span class="pre">ignore</span></tt> option is not in the configuration and not in the arguments, only the error codes <tt class="docutils literal"><span class="pre">E123/E133</span></tt>, <tt class="docutils literal"><span class="pre">E226</span></tt> and <tt class="docutils literal"><span class="pre">E241/E242</span></tt> are ignored (see below).</p> </div> <div class="section" id="error-codes"> <h2><a class="toc-backref" href="#id7">Error codes</a><a class="headerlink" href="#error-codes" title="Permalink to this headline">¶</a></h2> <p>This is the current list of error and warning codes:</p> <table border="1" class="docutils"> <colgroup> <col width="13%" /> <col width="88%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">code</th> <th class="head">sample message</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><strong>E1</strong></td> <td><em>Indentation</em></td> </tr> <tr class="row-odd"><td>E101</td> <td>indentation contains mixed spaces and tabs</td> </tr> <tr class="row-even"><td>E111</td> <td>indentation is not a multiple of four</td> </tr> <tr class="row-odd"><td>E112</td> <td>expected an indented block</td> </tr> <tr class="row-even"><td>E113</td> <td>unexpected indentation</td> </tr> <tr class="row-odd"><td> </td> <td> </td> </tr> <tr class="row-even"><td>E121 (^)</td> <td>continuation line under-indented for hanging indent</td> </tr> <tr class="row-odd"><td>E122 (^)</td> <td>continuation line missing indentation or outdented</td> </tr> <tr class="row-even"><td>E123 (*)</td> <td>closing bracket does not match indentation of opening bracket’s line</td> </tr> <tr class="row-odd"><td>E124 (^)</td> <td>closing bracket does not match visual indentation</td> </tr> <tr class="row-even"><td>E125 (^)</td> <td>continuation line with same indent as next logical line</td> </tr> <tr class="row-odd"><td>E126 (^)</td> <td>continuation line over-indented for hanging indent</td> </tr> <tr class="row-even"><td>E127 (^)</td> <td>continuation line over-indented for visual indent</td> </tr> <tr class="row-odd"><td>E128 (^)</td> <td>continuation line under-indented for visual indent</td> </tr> <tr class="row-even"><td>E129 (^)</td> <td>visually indented line with same indent as next logical line</td> </tr> <tr class="row-odd"><td>E131 (^)</td> <td>continuation line unaligned for hanging indent</td> </tr> <tr class="row-even"><td>E133 (*)</td> <td>closing bracket is missing indentation</td> </tr> <tr class="row-odd"><td> </td> <td> </td> </tr> <tr class="row-even"><td><strong>E2</strong></td> <td><em>Whitespace</em></td> </tr> <tr class="row-odd"><td>E201</td> <td>whitespace after ‘(‘</td> </tr> <tr class="row-even"><td>E202</td> <td>whitespace before ‘)’</td> </tr> <tr class="row-odd"><td>E203</td> <td>whitespace before ‘:’</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td>E211</td> <td>whitespace before ‘(‘</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td>E221</td> <td>multiple spaces before operator</td> </tr> <tr class="row-even"><td>E222</td> <td>multiple spaces after operator</td> </tr> <tr class="row-odd"><td>E223</td> <td>tab before operator</td> </tr> <tr class="row-even"><td>E224</td> <td>tab after operator</td> </tr> <tr class="row-odd"><td>E225</td> <td>missing whitespace around operator</td> </tr> <tr class="row-even"><td>E226 (*)</td> <td>missing whitespace around arithmetic operator</td> </tr> <tr class="row-odd"><td>E227</td> <td>missing whitespace around bitwise or shift operator</td> </tr> <tr class="row-even"><td>E228</td> <td>missing whitespace around modulo operator</td> </tr> <tr class="row-odd"><td> </td> <td> </td> </tr> <tr class="row-even"><td>E231</td> <td>missing whitespace after ‘,’</td> </tr> <tr class="row-odd"><td> </td> <td> </td> </tr> <tr class="row-even"><td>E241 (*)</td> <td>multiple spaces after ‘,’</td> </tr> <tr class="row-odd"><td>E242 (*)</td> <td>tab after ‘,’</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td>E251</td> <td>unexpected spaces around keyword / parameter equals</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td>E261</td> <td>at least two spaces before inline comment</td> </tr> <tr class="row-even"><td>E262</td> <td>inline comment should start with ‘# ‘</td> </tr> <tr class="row-odd"><td>E265</td> <td>block comment should start with ‘# ‘</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td>E271</td> <td>multiple spaces after keyword</td> </tr> <tr class="row-even"><td>E272</td> <td>multiple spaces before keyword</td> </tr> <tr class="row-odd"><td>E273</td> <td>tab after keyword</td> </tr> <tr class="row-even"><td>E274</td> <td>tab before keyword</td> </tr> <tr class="row-odd"><td> </td> <td> </td> </tr> <tr class="row-even"><td><strong>E3</strong></td> <td><em>Blank line</em></td> </tr> <tr class="row-odd"><td>E301</td> <td>expected 1 blank line, found 0</td> </tr> <tr class="row-even"><td>E302</td> <td>expected 2 blank lines, found 0</td> </tr> <tr class="row-odd"><td>E303</td> <td>too many blank lines (3)</td> </tr> <tr class="row-even"><td>E304</td> <td>blank lines found after function decorator</td> </tr> <tr class="row-odd"><td> </td> <td> </td> </tr> <tr class="row-even"><td><strong>E4</strong></td> <td><em>Import</em></td> </tr> <tr class="row-odd"><td>E401</td> <td>multiple imports on one line</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td><strong>E5</strong></td> <td><em>Line length</em></td> </tr> <tr class="row-even"><td>E501 (^)</td> <td>line too long (82 > 79 characters)</td> </tr> <tr class="row-odd"><td>E502</td> <td>the backslash is redundant between brackets</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td><strong>E7</strong></td> <td><em>Statement</em></td> </tr> <tr class="row-even"><td>E701</td> <td>multiple statements on one line (colon)</td> </tr> <tr class="row-odd"><td>E702</td> <td>multiple statements on one line (semicolon)</td> </tr> <tr class="row-even"><td>E703</td> <td>statement ends with a semicolon</td> </tr> <tr class="row-odd"><td>E711 (^)</td> <td>comparison to None should be ‘if cond is None:’</td> </tr> <tr class="row-even"><td>E712 (^)</td> <td>comparison to True should be ‘if cond is True:’ or ‘if cond:’</td> </tr> <tr class="row-odd"><td>E713</td> <td>test for membership should be ‘not in’</td> </tr> <tr class="row-even"><td>E714</td> <td>test for object identity should be ‘is not’</td> </tr> <tr class="row-odd"><td>E721</td> <td>do not compare types, use ‘isinstance()’</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td><strong>E9</strong></td> <td><em>Runtime</em></td> </tr> <tr class="row-even"><td>E901</td> <td>SyntaxError or IndentationError</td> </tr> <tr class="row-odd"><td>E902</td> <td>IOError</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td><strong>W1</strong></td> <td><em>Indentation warning</em></td> </tr> <tr class="row-even"><td>W191</td> <td>indentation contains tabs</td> </tr> <tr class="row-odd"><td> </td> <td> </td> </tr> <tr class="row-even"><td><strong>W2</strong></td> <td><em>Whitespace warning</em></td> </tr> <tr class="row-odd"><td>W291</td> <td>trailing whitespace</td> </tr> <tr class="row-even"><td>W292</td> <td>no newline at end of file</td> </tr> <tr class="row-odd"><td>W293</td> <td>blank line contains whitespace</td> </tr> <tr class="row-even"><td> </td> <td> </td> </tr> <tr class="row-odd"><td><strong>W3</strong></td> <td><em>Blank line warning</em></td> </tr> <tr class="row-even"><td>W391</td> <td>blank line at end of file</td> </tr> <tr class="row-odd"><td> </td> <td> </td> </tr> <tr class="row-even"><td><strong>W6</strong></td> <td><em>Deprecation warning</em></td> </tr> <tr class="row-odd"><td>W601</td> <td>.has_key() is deprecated, use ‘in’</td> </tr> <tr class="row-even"><td>W602</td> <td>deprecated form of raising exception</td> </tr> <tr class="row-odd"><td>W603</td> <td>‘<>’ is deprecated, use ‘!=’</td> </tr> <tr class="row-even"><td>W604</td> <td>backticks are deprecated, use ‘repr()’</td> </tr> </tbody> </table> <p><strong>(*)</strong> In the default configuration, the checks <strong>E123</strong>, <strong>E133</strong>, <strong>E226</strong>, <strong>E241</strong> and <strong>E242</strong> are ignored because they are not rules unanimously accepted, and <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP 8</a> does not enforce them. The check <strong>E133</strong> is mutually exclusive with check <strong>E123</strong>. Use switch <tt class="docutils literal"><span class="pre">--hang-closing</span></tt> to report <strong>E133</strong> instead of <strong>E123</strong>.</p> <p><strong>(^)</strong> These checks can be disabled at the line level using the <tt class="docutils literal"><span class="pre">#</span> <span class="pre">noqa</span></tt> special comment. This possibility should be reserved for special cases.</p> <blockquote> <div><em>Special cases aren’t special enough to break the rules.</em></div></blockquote> <p>Note: most errors can be listed with such one-liner:</p> <div class="highlight-python"><div class="highlight"><pre>$ python pep8.py --first --select E,W testsuite/ --format '%(code)s: %(text)s' </pre></div> </div> </div> <div class="section" id="related-tools"> <span id="id1"></span><h2><a class="toc-backref" href="#id8">Related tools</a><a class="headerlink" href="#related-tools" title="Permalink to this headline">¶</a></h2> <p>The <a class="reference external" href="https://flake8.readthedocs.org">flake8 checker</a> is a wrapper around <tt class="docutils literal"><span class="pre">pep8</span></tt> and similar tools. It supports plugins.</p> <p>Other tools which use <tt class="docutils literal"><span class="pre">pep8</span></tt> are referenced in the Wiki: <a class="reference external" href="https://github.com/jcrocholl/pep8/wiki/RelatedTools">list of related tools</a>.</p> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Introduction</a><ul> <li><a class="reference internal" href="#features">Features</a></li> <li><a class="reference internal" href="#disclaimer">Disclaimer</a></li> <li><a class="reference internal" href="#installation">Installation</a></li> <li><a class="reference internal" href="#example-usage-and-output">Example usage and output</a></li> <li><a class="reference internal" href="#configuration">Configuration</a></li> <li><a class="reference internal" href="#error-codes">Error codes</a></li> <li><a class="reference internal" href="#related-tools">Related tools</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="index.html" title="previous chapter">pep8’s documentation</a></p> <h4>Next topic</h4> <p class="topless"><a href="advanced.html" title="next chapter">Advanced usage</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/intro.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="advanced.html" title="Advanced usage" >next</a> |</li> <li class="right" > <a href="index.html" title="pep8’s documentation" >previous</a> |</li> <li><a href="index.html">pep8 1.5.7 documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2012-2013, Florent Xicluna. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3. </div> </body> </html>