pre-commit/flake8
1
0
Fork 0
mirror of https://github.com/PyCQA/flake8.git synced 2026-03-29 18:46:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
flake8/README

274 lines
7.5 KiB
Text
Raw Blame History

======
Flake8
======
Flake8 is a wrapper around these tools:
- PyFlakes
- pep8
- Ned's McCabe script
Flake8 runs all tools by launching the single 'flake8' script, but ignores pep8
and PyFlakes extended options and just uses defaults. It displays the warnings
in a per-file, merged output.
It also adds a few features:
- files that contains with this header are skipped::
# flake8: noqa
- lines that contains a "# NOQA" comment at the end will not issue a warning.
- a Mercurial hook.
- a McCabe complexity checker.
QuickStart
==========
To run flake8 just invoke it against any directory or Python module::
$ flake8 coolproject
coolproject/mod.py:1027: local variable 'errors' is assigned to but never used
coolproject/mod.py:97: 'shutil' imported but unused
coolproject/mod.py:729: redefinition of function 'readlines' from line 723
coolproject/mod.py:1028: local variable 'errors' is assigned to but never used
coolproject/mod.py:625:17: E225 missing whitespace around operato
The output of PyFlakes *and* pep8 is merged and returned.
flake8 offers an extra option: --max-complexity, which will emit a warning if the
McCabe complexityu of a function is higher that the value. By default it's
deactivated::
$ bin/flake8 --max-complexity 12 flake8
coolproject/mod.py:97: 'shutil' imported but unused
coolproject/mod.py:729: redefinition of function 'readlines' from line 723
coolproject/mod.py:1028: local variable 'errors' is assigned to but never used
coolproject/mod.py:625:17: E225 missing whitespace around operator
coolproject/mod.py:452:1: 'missing_whitespace_around_operator' is too complex (18)
coolproject/mod.py:939:1: 'Checker.check_all' is too complex (12)
coolproject/mod.py:1204:1: 'selftest' is too complex (14)
This feature is quite useful to detect over-complex code. According to McCabe, anything
that goes beyond 10 is too complex.
See https://en.wikipedia.org/wiki/Cyclomatic_complexity.
Mercurial hook
==============
To use the Mercurial hook on any *commit* or *qrefresh*, change your .hg/rc file
like this::
[hooks]
commit = python:flake8.run.hg_hook
qrefresh = python:flake8.run.hg_hook
[flake8]
strict = 0
complexity = 12
If *strict* option is set to **1**, any warning will block the commit. When
*strict* is set to **0**, warnings are just displayed in the standard output.
*complexity* defines the maximum McCabe complexity allowed before a warning
is emited. If you don't specify it it's just ignored. If specified, must
be a positive value. 12 is usually a good value.
Git hook
========
To use the Git hook on any *commit*, add a **pre-commit** file in the
*.git/hooks* directory containing::
#!/usr/bin/python
import sys
from flake8.run import git_hook
COMPLEXITY = 10
STRICT = False
if __name__ == '__main__':
sys.exit(git_hook(complexity=COMPLEXITY, strict=STRICT, ignore='E501'))
If *strict* option is set to **True**, any warning will block the commit. When
*strict* is set to **False** or omited, warnings are just displayed in the
standard output.
*complexity* defines the maximum McCabe complexity allowed before a warning
is emited. If you don't specify it or set it to **-1**, it's just ignored.
If specified, it must be a positive value. 12 is usually a good value.
Also, make sure the file is executable and adapt the shebang line so it
point to your python interpreter.
Buildout integration
=====================
In order to use Flake8 inside a buildout, edit your buildout.cfg and add this::
[buildout]
parts +=
...
flake8
[flake8]
recipe = zc.recipe.egg
eggs = flake8
${buildout:eggs}
entry-points =
flake8=flake8.run:main
Original projects
=================
Flake8 is just a glue project, all the merits go to the creators of the original
projects:
- pep8: http://github.com/jcrocholl/pep8/
- PyFlakes: http://divmod.org/trac/wiki/DivmodPyflakes
- McCabe: http://nedbatchelder.com/blog/200803/python_code_complexity_microtool.html
Warning / Error codes
=====================
Below are lists of all warning and error codes flake8 will generate, broken
out by component.
pep8:
- E101: indentation contains mixed spaces and tabs
- E111: indentation is not a multiple of four
- E112: expected an indented block
- E113: unexpected indentation
- E201: whitespace after char
- E202: whitespace before char
- E203: whitespace before char
- E211: whitespace before text
- E223: tab / multiple spaces before operator
- E224: tab / multiple spaces after operator
- E225: missing whitespace around operator
- E225: missing whitespace around operator
- E231: missing whitespace after char
- E241: multiple spaces after separator
- E242: tab after separator
- E251: no spaces around keyword / parameter equals
- E262: inline comment should start with '# '
- E301: expected 1 blank line, found 0
- E302: expected 2 blank lines, found <n>
- E303: too many blank lines (<n>)
- E304: blank lines found after function decorator
- E401: multiple imports on one line
- E501: line too long (<n> characters)
- E701: multiple statements on one line (colon)
- E702: multiple statements on one line (semicolon)
- W191: indentation contains tabs
- W291: trailing whitespace
- W292: no newline at end of file
- W293: blank line contains whitespace
- W391: blank line at end of file
- W601: .has_key() is deprecated, use 'in'
- W602: deprecated form of raising exception
- W603: '<>' is deprecated, use '!='
- W604: backticks are deprecated, use 'repr()'
pyflakes:
- W402: <module> imported but unused
- W403: import <module> from line <n> shadowed by loop variable
- W404: 'from <module> import ``*``' used; unable to detect undefined names
- W405: future import(s) <name> after other statements
- W801: redefinition of unused <name> from line <n>
- W802: undefined name <name>
- W803: undefined name <name> in __all__
- W804: local variable <name> (defined in enclosing scope on line <n>) referenced before assignment
- W805: duplicate argument <name> in function definition
- W806: redefinition of function <name> from line <n>
- W806: local variable <name> is assigned to but never used
McCabe:
- W901: '<function_name>' is too complex ('<complexity_level>')
CHANGES
=======
1.5
---
???
1.4 - 2012-07-12
----------------
- git_hook: Only check staged changes for compliance
- use pep8 1.2
1.3.1 - 2012-05-19
------------------
- fixed support for Python 2.5
1.3 - 2012-03-12
----------------
- fixed false W402 warning on exception blocks.
1.2 - 2012-02-12
----------------
- added a git hook
- now python 3 compatible
- mccabe and pyflakes have warning codes like pep8 now
1.1 - 2012-02-14
----------------
- fixed the value returned by --version
- allow the flake8: header to be more generic
- fixed the "hg hook raises 'physical lines'" bug
- allow three argument form of raise
- now uses setuptools if available, for 'develop' command
1.0 - 2011-11-29
----------------
- Deactivates by default the complexity checker
- Introduces the complexity option in the HG hook and the command line.
0.9 - 2011-11-09
----------------
- update pep8 version to 0.6.1
- mccabe check: gracefully handle compile failure
0.8 - 2011-02-27
----------------
- fixed hg hook
- discard unexisting files on hook check
0.7 - 2010-02-18
----------------
- Fix pep8 intialization when run through Hg
- Make pep8 short options work when run throug the command line
- skip duplicates when controlling files via Hg
0.6 - 2010-02-15
----------------
- Fix the McCabe metric on some loops
Reference in a new issue View git blame Copy permalink