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