From 8af0f1ed98f8ce8555538747d4fdb60c1d2e45c4 Mon Sep 17 00:00:00 2001 From: Florent Xicluna Date: Wed, 20 Feb 2013 22:50:12 +0100 Subject: [PATCH] Add information to the README.rst --- README.rst | 183 +++++++++++++++++++++++++++++------------------------ 1 file changed, 101 insertions(+), 82 deletions(-) diff --git a/README.rst b/README.rst index f6b5cc4..912ba17 100644 --- a/README.rst +++ b/README.rst @@ -8,22 +8,20 @@ Flake8 is a wrapper around these tools: - 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. +Flake8 runs all the tools by launching the single 'flake8' script. +It displays the warnings in a per-file, merged output. It also adds a few features: -- files that contains with this header are skipped:: +- files that contain this line are skipped:: # flake8: noqa -- lines that contain a "# NOQA" comment at the end will not issue pyflakes - warnings. -- lines that contain a "# NOPEP8" comment at the end will not issue pep8 - warnings. -- a Mercurial hook. +- lines that contain a "# noqa" comment at the end will not issue warnings. +- a Git and a Mercurial hook. - a McCabe complexity checker. +- extendable through ``flake8.extension`` entry points + QuickStart ========== @@ -37,13 +35,14 @@ To run flake8 just invoke it against any directory or Python module:: 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. +The output of PyFlakes *and* pep8 (and the optional plugins) are 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 +flake8 offers an extra option: --max-complexity, which will emit a warning if +the McCabe complexity of a function is higher than the value. By default it's deactivated:: - $ bin/flake8 --max-complexity 12 flake8 + $ 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 @@ -52,16 +51,37 @@ deactivated:: 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. +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. +Configuration +------------- + +The behaviour may be configured at two levels. + +The user settings are read from the ``~/.config/flake8`` file. +Example:: + + [flake8] + ignore = E226,E302,E41 + max-line-length = 160 + +At the project level, a ``tox.ini`` file or a ``setup.cfg`` file is read +if present. Only the first file is considered. If this file does not +have a ``[flake8]`` section, no project specific configuration is loaded. + +If the ``ignore`` option is not in the configuration and not in the arguments, +only the error codes ``E226`` and ``E241/E242`` are ignored +(see codes in the table below). + + Mercurial hook ============== -To use the Mercurial hook on any *commit* or *qrefresh*, change your .hg/rc file -like this:: +To use the Mercurial hook on any *commit* or *qrefresh*, change your .hg/hgrc +file like this:: [hooks] commit = python:flake8.run.hg_hook @@ -73,11 +93,12 @@ like this:: 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. +*strict* is set to **0**, warnings are just printed to 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. +is emitted. If you don't specify it, it's just ignored. If specified, it must +be a positive value. 12 is usually a good value. + Git hook ======== @@ -97,18 +118,18 @@ To use the Git hook on any *commit*, add a **pre-commit** file in the 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 +*strict* is set to **False** or omitted, warnings are just printed to 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. +is emitted. 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. -*lazy* when set to ``True`` will also take into account files not added to the +*lazy* when set to ``True`` will also take into account files not added to the index. Also, make sure the file is executable and adapt the shebang line so it -point to your python interpreter. +points to your Python interpreter. Buildout integration @@ -134,7 +155,7 @@ setuptools integration ====================== If setuptools is available, Flake8 provides a command that checks the -Python files declared by your project. To use it, add flake8 to your +Python files declared by your project. To use it, add flake8 to your setup_requires:: setup( @@ -147,8 +168,8 @@ setup_requires:: ) Running ``python setup.py flake8`` on the command line will check the -files listed in your ``py_modules`` and ``packages``. If any warnings -are found, the command will exit with an error code:: +files listed in your ``py_modules`` and ``packages``. If any warning +is found, the command will exit with an error code:: $ python setup.py flake8 @@ -160,68 +181,66 @@ Original projects Flake8 is just a glue project, all the merits go to the creators of the original projects: -- pep8: https://github.com/jcrocholl/pep8/ -- PyFlakes: http://divmod.org/trac/wiki/DivmodPyflakes -- flakey: https://bitbucket.org/icordasc/flakey +- pep8: https://github.com/jcrocholl/pep8 +- PyFlakes: https://launchpad.net/pyflakes - 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. +The convention of Flake8 is to assign a code to each error or warning, like +the ``pep8`` tool. These codes are used to configure the list of errors +which are selected or ignored. -pep8: +Each code consists of an upper case ASCII letter followed by three digits. +The recommendation is to use a different prefix for each plugin. -- 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 -- E303: too many blank lines () -- E304: blank lines found after function decorator -- E401: multiple imports on one line -- E501: line too long ( 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()' +A list of the known prefixes is published below: -flakey: +- ``E***``/``W***``: `pep8 errors and warnings + `_ +- ``F***``: PyFlakes codes (see below) +- ``C9**``: McCabe complexity plugin `mccabe + `_ +- ``N8**``: Naming Conventions plugin `flint-naming + `_ -- W402: imported but unused -- W403: import from line shadowed by loop variable -- W404: 'from import ``*``' used; unable to detect undefined names -- W405: future import(s) after other statements -- W801: redefinition of unused from line -- W802: undefined name -- W803: undefined name in __all__ -- W804: local variable (defined in enclosing scope on line ) referenced before assignment -- W805: duplicate argument in function definition -- W806: redefinition of function from line -- W806: local variable is assigned to but never used -McCabe: +The original PyFlakes does not provide error codes. Flake8 patches the +PyFlakes messages to add the following codes: -- W901: '' is too complex ('') ++------+--------------------------------------------------------------------+ +| code | sample message | ++======+====================================================================+ +| F401 | ``module`` imported but unused | ++------+--------------------------------------------------------------------+ +| F402 | import ``module`` from line ``N`` shadowed by loop variable | ++------+--------------------------------------------------------------------+ +| F403 | 'from ``module`` import \*' used; unable to detect undefined names | ++------+--------------------------------------------------------------------+ +| F404 | future import(s) ``name`` after other statements | ++------+--------------------------------------------------------------------+ ++------+--------------------------------------------------------------------+ +| F811 | redefinition of unused ``name`` from line ``N`` | ++------+--------------------------------------------------------------------+ +| F812 | list comprehension redefines ``name`` from line ``N`` | ++------+--------------------------------------------------------------------+ +| F821 | undefined name ``name`` | ++------+--------------------------------------------------------------------+ +| F822 | undefined name ``name`` in __all__ | ++------+--------------------------------------------------------------------+ +| F823 | local variable ``name`` ... referenced before assignment | ++------+--------------------------------------------------------------------+ +| F831 | duplicate argument ``name`` in function definition | ++------+--------------------------------------------------------------------+ +| F841 | local variable ``name`` is assigned to but never used | ++------+--------------------------------------------------------------------+ + + +Links +----- + +* `pep8 documentation `_ + +* `flake8 documentation `_