third_party/pep8/docs/intro.rst

   1 .. currentmodule:: pep8
   2
   3 Introduction
   4 ============
   5
   6 pep8 is a tool to check your Python code against some of the style
   7 conventions in `PEP 8`_.
   8
   9 .. contents::
  10    :local:
  11
  12
  13 Features
  14 --------
  15
  16 * Plugin architecture: Adding new checks is easy.
  17
  18 * Parseable output: Jump to error location in your editor.
  19
  20 * Small: Just one Python file, requires only stdlib.  You can use just
  21   the pep8.py file for this purpose.
  22
  23 * Comes with a comprehensive test suite.
  24
  25
  26 Disclaimer
  27 ----------
  28
  29 This utility does not enforce every single rule of PEP 8.  It helps to
  30 verify that some coding conventions are applied but it does not intend
  31 to be exhaustive.  Some rules cannot be expressed with a simple algorithm,
  32 and other rules are only guidelines which you could circumvent when you
  33 need to.
  34
  35 Always remember this statement from `PEP 8`_:
  36
  37   *A style guide is about consistency. Consistency with this style guide is
  38   important. Consistency within a project is more important. Consistency
  39   within one module or function is most important.*
  40
  41
  42 Among other things, these features are currently not in the scope of
  43 the ``pep8`` library:
  44
  45 * **naming conventions**: this kind of feature is supported through plugins.
  46   Install `flake8 <https://pypi.python.org/pypi/flake8>`_ and the
  47   `pep8-naming extension <https://pypi.python.org/pypi/pep8-naming>`_ to use
  48   this feature.
  49 * **docstring conventions**: they are not in the scope of this library;
  50   see the `pep257 project <https://github.com/GreenSteam/pep257>`_.
  51 * **automatic fixing**: see the section *PEP8 Fixers* in the
  52   :ref:`related tools <related-tools>` page.
  53
  54
  55 Installation
  56 ------------
  57
  58 You can install, upgrade, uninstall pep8.py with these commands::
  59
  60   $ pip install pep8
  61   $ pip install --upgrade pep8
  62   $ pip uninstall pep8
  63
  64 There's also a package for Debian/Ubuntu, but it's not always the
  65 latest version::
  66
  67   $ sudo apt-get install pep8
  68
  69
  70 Example usage and output
  71 ------------------------
  72
  73 ::
  74
  75   $ pep8 --first optparse.py
  76   optparse.py:69:11: E401 multiple imports on one line
  77   optparse.py:77:1: E302 expected 2 blank lines, found 1
  78   optparse.py:88:5: E301 expected 1 blank line, found 0
  79   optparse.py:222:34: W602 deprecated form of raising exception
  80   optparse.py:347:31: E211 whitespace before '('
  81   optparse.py:357:17: E201 whitespace after '{'
  82   optparse.py:472:29: E221 multiple spaces before operator
  83   optparse.py:544:21: W601 .has_key() is deprecated, use 'in'
  84
  85 You can also make pep8.py show the source code for each error, and
  86 even the relevant text from PEP 8::
  87
  88   $ pep8 --show-source --show-pep8 testsuite/E40.py
  89   testsuite/E40.py:2:10: E401 multiple imports on one line
  90   import os, sys
  91            ^
  92       Imports should usually be on separate lines.
  93
  94       Okay: import os\nimport sys
  95       E401: import sys, os
  96
  97
  98 Or you can display how often each error was found::
  99
 100   $ pep8 --statistics -qq Python-2.5/Lib
 101   232     E201 whitespace after '['
 102   599     E202 whitespace before ')'
 103   631     E203 whitespace before ','
 104   842     E211 whitespace before '('
 105   2531    E221 multiple spaces before operator
 106   4473    E301 expected 1 blank line, found 0
 107   4006    E302 expected 2 blank lines, found 1
 108   165     E303 too many blank lines (4)
 109   325     E401 multiple imports on one line
 110   3615    E501 line too long (82 characters)
 111   612     W601 .has_key() is deprecated, use 'in'
 112   1188    W602 deprecated form of raising exception
 113
 114 You can also make pep8.py show the error text in different formats by using --format having options default/pylint/custom::
 115
 116   $ pep8 testsuite/E40.py --format=default
 117   testsuite/E40.py:2:10: E401 multiple imports on one line
 118
 119   $ pep8 testsuite/E40.py --format=pylint
 120   testsuite/E40.py:2: [E401] multiple imports on one line
 121
 122   $ pep8 testsuite/E40.py --format='%(path)s|%(row)d|%(col)d| %(code)s %(text)s'
 123   testsuite/E40.py|2|10| E401 multiple imports on one line
 124
 125 Variables in the ``custom`` format option
 126
 127 +----------------+------------------+
 128 |   Variable     |   Significance   |
 129 +================+==================+
 130 | ``path``       | File name        |
 131 +----------------+------------------+
 132 | ``row``        | Row number       |
 133 +----------------+------------------+
 134 | ``col``        | Column number    |
 135 +----------------+------------------+
 136 | ``code``       | Error code       |
 137 +----------------+------------------+
 138 | ``text``       | Error text       |
 139 +----------------+------------------+
 140
 141 Quick help is available on the command line::
 142
 143   $ pep8 -h
 144   Usage: pep8 [options] input ...
 145
 146   Options:
 147     --version            show program's version number and exit
 148     -h, --help           show this help message and exit
 149     -v, --verbose        print status messages, or debug with -vv
 150     -q, --quiet          report only file names, or nothing with -qq
 151     --first              show first occurrence of each error
 152     --exclude=patterns   exclude files or directories which match these comma
 153                          separated patterns (default: .svn,CVS,.bzr,.hg,.git)
 154     --filename=patterns  when parsing directories, only check filenames matching
 155                          these comma separated patterns (default: *.py)
 156     --select=errors      select errors and warnings (e.g. E,W6)
 157     --ignore=errors      skip errors and warnings (e.g. E4,W)
 158     --show-source        show source code for each error
 159     --show-pep8          show text of PEP 8 for each error (implies --first)
 160     --statistics         count errors and warnings
 161     --count              print total number of errors and warnings to standard
 162                          error and set exit code to 1 if total is not null
 163     --max-line-length=n  set maximum allowed line length (default: 79)
 164     --hang-closing       hang closing bracket instead of matching indentation of
 165                          opening bracket's line
 166     --format=format      set the error format [default|pylint|<custom>]
 167     --diff               report only lines changed according to the unified diff
 168                          received on STDIN
 169
 170     Testing Options:
 171       --benchmark        measure processing speed
 172
 173     Configuration:
 174       The project options are read from the [pep8] section of the tox.ini
 175       file or the setup.cfg file located in any parent folder of the path(s)
 176       being processed.  Allowed options are: exclude, filename, select,
 177       ignore, max-line-length, hang-closing, count, format, quiet, show-pep8,
 178       show-source, statistics, verbose.
 179
 180       --config=path      user config file location (default: ~/.config/pep8)
 181
 182
 183 Configuration
 184 -------------
 185
 186 The behaviour may be configured at two levels, the user and project levels.
 187
 188 At the user level, settings are read from the following locations:
 189
 190 If on Windows:
 191     ``~\.pep8``
 192
 193 Otherwise, if the :envvar:`XDG_CONFIG_HOME` environment variable is defined:
 194     ``XDG_CONFIG_HOME/pep8``
 195
 196 Else if :envvar:`XDG_CONFIG_HOME` is not defined:
 197     ``~/.config/pep8``
 198
 199 Example::
 200
 201   [pep8]
 202   ignore = E226,E302,E41
 203   max-line-length = 160
 204
 205 At the project level, a ``setup.cfg`` file or a ``tox.ini`` file is read if
 206 present (``.pep8`` file is also supported, but it is deprecated).  If none of
 207 these files have a ``[pep8]`` section, no project specific configuration is
 208 loaded.
 209
 210 If the ``ignore`` option is not in the configuration and not in the arguments,
 211 only the error codes ``E123/E133``, ``E226`` and ``E241/E242`` are ignored
 212 (see below).
 213
 214
 215 Error codes
 216 -----------
 217
 218 This is the current list of error and warning codes:
 219
 220 +----------+----------------------------------------------------------------------+
 221 | code     | sample message                                                       |
 222 +==========+======================================================================+
 223 | **E1**   | *Indentation*                                                        |
 224 +----------+----------------------------------------------------------------------+
 225 | E101     | indentation contains mixed spaces and tabs                           |
 226 +----------+----------------------------------------------------------------------+
 227 | E111     | indentation is not a multiple of four                                |
 228 +----------+----------------------------------------------------------------------+
 229 | E112     | expected an indented block                                           |
 230 +----------+----------------------------------------------------------------------+
 231 | E113     | unexpected indentation                                               |
 232 +----------+----------------------------------------------------------------------+
 233 | E114     | indentation is not a multiple of four (comment)                      |
 234 +----------+----------------------------------------------------------------------+
 235 | E115     | expected an indented block (comment)                                 |
 236 +----------+----------------------------------------------------------------------+
 237 | E116     | unexpected indentation (comment)                                     |
 238 +----------+----------------------------------------------------------------------+
 239 +----------+----------------------------------------------------------------------+
 240 | E121 (*^)| continuation line under-indented for hanging indent                  |
 241 +----------+----------------------------------------------------------------------+
 242 | E122 (^) | continuation line missing indentation or outdented                   |
 243 +----------+----------------------------------------------------------------------+
 244 | E123 (*) | closing bracket does not match indentation of opening bracket's line |
 245 +----------+----------------------------------------------------------------------+
 246 | E124 (^) | closing bracket does not match visual indentation                    |
 247 +----------+----------------------------------------------------------------------+
 248 | E125 (^) | continuation line with same indent as next logical line              |
 249 +----------+----------------------------------------------------------------------+
 250 | E126 (*^)| continuation line over-indented for hanging indent                   |
 251 +----------+----------------------------------------------------------------------+
 252 | E127 (^) | continuation line over-indented for visual indent                    |
 253 +----------+----------------------------------------------------------------------+
 254 | E128 (^) | continuation line under-indented for visual indent                   |
 255 +----------+----------------------------------------------------------------------+
 256 | E129 (^) | visually indented line with same indent as next logical line         |
 257 +----------+----------------------------------------------------------------------+
 258 | E131 (^) | continuation line unaligned for hanging indent                       |
 259 +----------+----------------------------------------------------------------------+
 260 | E133 (*) | closing bracket is missing indentation                               |
 261 +----------+----------------------------------------------------------------------+
 262 +----------+----------------------------------------------------------------------+
 263 | **E2**   | *Whitespace*                                                         |
 264 +----------+----------------------------------------------------------------------+
 265 | E201     | whitespace after '('                                                 |
 266 +----------+----------------------------------------------------------------------+
 267 | E202     | whitespace before ')'                                                |
 268 +----------+----------------------------------------------------------------------+
 269 | E203     | whitespace before ':'                                                |
 270 +----------+----------------------------------------------------------------------+
 271 +----------+----------------------------------------------------------------------+
 272 | E211     | whitespace before '('                                                |
 273 +----------+----------------------------------------------------------------------+
 274 +----------+----------------------------------------------------------------------+
 275 | E221     | multiple spaces before operator                                      |
 276 +----------+----------------------------------------------------------------------+
 277 | E222     | multiple spaces after operator                                       |
 278 +----------+----------------------------------------------------------------------+
 279 | E223     | tab before operator                                                  |
 280 +----------+----------------------------------------------------------------------+
 281 | E224     | tab after operator                                                   |
 282 +----------+----------------------------------------------------------------------+
 283 | E225     | missing whitespace around operator                                   |
 284 +----------+----------------------------------------------------------------------+
 285 | E226 (*) | missing whitespace around arithmetic operator                        |
 286 +----------+----------------------------------------------------------------------+
 287 | E227     | missing whitespace around bitwise or shift operator                  |
 288 +----------+----------------------------------------------------------------------+
 289 | E228     | missing whitespace around modulo operator                            |
 290 +----------+----------------------------------------------------------------------+
 291 +----------+----------------------------------------------------------------------+
 292 | E231     | missing whitespace after ',', ';', or ':'                            |
 293 +----------+----------------------------------------------------------------------+
 294 +----------+----------------------------------------------------------------------+
 295 | E241 (*) | multiple spaces after ','                                            |
 296 +----------+----------------------------------------------------------------------+
 297 | E242 (*) | tab after ','                                                        |
 298 +----------+----------------------------------------------------------------------+
 299 +----------+----------------------------------------------------------------------+
 300 | E251     | unexpected spaces around keyword / parameter equals                  |
 301 +----------+----------------------------------------------------------------------+
 302 +----------+----------------------------------------------------------------------+
 303 | E261     | at least two spaces before inline comment                            |
 304 +----------+----------------------------------------------------------------------+
 305 | E262     | inline comment should start with '# '                                |
 306 +----------+----------------------------------------------------------------------+
 307 | E265     | block comment should start with '# '                                 |
 308 +----------+----------------------------------------------------------------------+
 309 | E266     | too many leading '#' for block comment                               |
 310 +----------+----------------------------------------------------------------------+
 311 +----------+----------------------------------------------------------------------+
 312 | E271     | multiple spaces after keyword                                        |
 313 +----------+----------------------------------------------------------------------+
 314 | E272     | multiple spaces before keyword                                       |
 315 +----------+----------------------------------------------------------------------+
 316 | E273     | tab after keyword                                                    |
 317 +----------+----------------------------------------------------------------------+
 318 | E274     | tab before keyword                                                   |
 319 +----------+----------------------------------------------------------------------+
 320 +----------+----------------------------------------------------------------------+
 321 | **E3**   | *Blank line*                                                         |
 322 +----------+----------------------------------------------------------------------+
 323 | E301     | expected 1 blank line, found 0                                       |
 324 +----------+----------------------------------------------------------------------+
 325 | E302     | expected 2 blank lines, found 0                                      |
 326 +----------+----------------------------------------------------------------------+
 327 | E303     | too many blank lines (3)                                             |
 328 +----------+----------------------------------------------------------------------+
 329 | E304     | blank lines found after function decorator                           |
 330 +----------+----------------------------------------------------------------------+
 331 +----------+----------------------------------------------------------------------+
 332 | **E4**   | *Import*                                                             |
 333 +----------+----------------------------------------------------------------------+
 334 | E401     | multiple imports on one line                                         |
 335 +----------+----------------------------------------------------------------------+
 336 | E402     | module level import not at top of file                               |
 337 +----------+----------------------------------------------------------------------+
 338 +----------+----------------------------------------------------------------------+
 339 | **E5**   | *Line length*                                                        |
 340 +----------+----------------------------------------------------------------------+
 341 | E501 (^) | line too long (82 > 79 characters)                                   |
 342 +----------+----------------------------------------------------------------------+
 343 | E502     | the backslash is redundant between brackets                          |
 344 +----------+----------------------------------------------------------------------+
 345 +----------+----------------------------------------------------------------------+
 346 | **E7**   | *Statement*                                                          |
 347 +----------+----------------------------------------------------------------------+
 348 | E701     | multiple statements on one line (colon)                              |
 349 +----------+----------------------------------------------------------------------+
 350 | E702     | multiple statements on one line (semicolon)                          |
 351 +----------+----------------------------------------------------------------------+
 352 | E703     | statement ends with a semicolon                                      |
 353 +----------+----------------------------------------------------------------------+
 354 | E704 (*) | multiple statements on one line (def)                                |
 355 +----------+----------------------------------------------------------------------+
 356 | E711 (^) | comparison to None should be 'if cond is None:'                      |
 357 +----------+----------------------------------------------------------------------+
 358 | E712 (^) | comparison to True should be 'if cond is True:' or 'if cond:'        |
 359 +----------+----------------------------------------------------------------------+
 360 | E713     | test for membership should be 'not in'                               |
 361 +----------+----------------------------------------------------------------------+
 362 | E714     | test for object identity should be 'is not'                          |
 363 +----------+----------------------------------------------------------------------+
 364 | E721     | do not compare types, use 'isinstance()'                             |
 365 +----------+----------------------------------------------------------------------+
 366 | E731     | do not assign a lambda expression, use a def                         |
 367 +----------+----------------------------------------------------------------------+
 368 +----------+----------------------------------------------------------------------+
 369 | **E9**   | *Runtime*                                                            |
 370 +----------+----------------------------------------------------------------------+
 371 | E901     | SyntaxError or IndentationError                                      |
 372 +----------+----------------------------------------------------------------------+
 373 | E902     | IOError                                                              |
 374 +----------+----------------------------------------------------------------------+
 375 +----------+----------------------------------------------------------------------+
 376 | **W1**   | *Indentation warning*                                                |
 377 +----------+----------------------------------------------------------------------+
 378 | W191     | indentation contains tabs                                            |
 379 +----------+----------------------------------------------------------------------+
 380 +----------+----------------------------------------------------------------------+
 381 | **W2**   | *Whitespace warning*                                                 |
 382 +----------+----------------------------------------------------------------------+
 383 | W291     | trailing whitespace                                                  |
 384 +----------+----------------------------------------------------------------------+
 385 | W292     | no newline at end of file                                            |
 386 +----------+----------------------------------------------------------------------+
 387 | W293     | blank line contains whitespace                                       |
 388 +----------+----------------------------------------------------------------------+
 389 +----------+----------------------------------------------------------------------+
 390 | **W3**   | *Blank line warning*                                                 |
 391 +----------+----------------------------------------------------------------------+
 392 | W391     | blank line at end of file                                            |
 393 +----------+----------------------------------------------------------------------+
 394 +----------+----------------------------------------------------------------------+
 395 | **W6**   | *Deprecation warning*                                                |
 396 +----------+----------------------------------------------------------------------+
 397 | W601     | .has_key() is deprecated, use 'in'                                   |
 398 +----------+----------------------------------------------------------------------+
 399 | W602     | deprecated form of raising exception                                 |
 400 +----------+----------------------------------------------------------------------+
 401 | W603     | '<>' is deprecated, use '!='                                         |
 402 +----------+----------------------------------------------------------------------+
 403 | W604     | backticks are deprecated, use 'repr()'                               |
 404 +----------+----------------------------------------------------------------------+
 405
 406
 407 **(*)** In the default configuration, the checks **E121**, **E123**, **E126**,
 408 **E133**, **E226**, **E241**, **E242** and **E704** are ignored because they
 409 are not rules unanimously accepted, and `PEP 8`_ does not enforce them.  The
 410 check **E133** is mutually exclusive with check **E123**.  Use switch ``--hang-
 411 closing`` to report **E133** instead of **E123**.
 412
 413 **(^)** These checks can be disabled at the line level using the ``# noqa``
 414 special comment.  This possibility should be reserved for special cases.
 415
 416   *Special cases aren't special enough to break the rules.*
 417
 418
 419 Note: most errors can be listed with such one-liner::
 420
 421   $ python pep8.py --first --select E,W testsuite/ --format '%(code)s: %(text)s'
 422
 423
 424 .. _related-tools:
 425
 426 Related tools
 427 -------------
 428
 429 The `flake8 checker <https://flake8.readthedocs.org>`_ is a wrapper around
 430 ``pep8`` and similar tools. It supports plugins.
 431
 432 Other tools which use ``pep8`` are referenced in the Wiki: `list of related
 433 tools <https://github.com/jcrocholl/pep8/wiki/RelatedTools>`_.
 434
 435 .. _PEP 8: http://www.python.org/dev/peps/pep-0008/