diff options
Diffstat (limited to 'docs/source/user/invocation.rst')
| -rw-r--r-- | docs/source/user/invocation.rst | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/docs/source/user/invocation.rst b/docs/source/user/invocation.rst new file mode 100644 index 0000000..383e93a --- /dev/null +++ b/docs/source/user/invocation.rst @@ -0,0 +1,144 @@ +.. _invocation: + +================= + Invoking Flake8 +================= + +Once you have :ref:`installed <installation-guide>` |Flake8|, you can begin +using it. Most of the time, you will be able to generically invoke |Flake8| +like so: + +.. prompt:: bash + + flake8 ... + +Where you simply allow the shell running in your terminal to locate |Flake8|. +In some cases, though, you may have installed |Flake8| for multiple versions +of Python (e.g., Python 2.7 and Python 3.5) and you need to call a specific +version. In that case, you will have much better results using: + +.. prompt:: bash + + python2.7 -m flake8 + +Or + +.. prompt:: bash + + python3.5 -m flake8 + +Since that will tell the correct version of Python to run |Flake8|. + +.. note:: + + Installing |Flake8| once will not install it on both Python 2.7 and + Python 3.5. It will only install it for the version of Python that + is running pip. + +It is also possible to specify command-line options directly to |Flake8|: + +.. prompt:: bash + + flake8 --select E123 + +Or + +.. prompt:: bash + + python<version> -m flake8 --select E123 + +.. note:: + + This is the last time we will show both versions of an invocation. + From now on, we'll simply use ``flake8`` and assume that the user + knows they can instead use ``python<version> -m flake8`` instead. + +It's also possible to narrow what |Flake8| will try to check by specifying +exactly the paths and directories you want it to check. Let's assume that +we have a directory with python files and sub-directories which have python +files (and may have more sub-directories) called ``my_project``. Then if +we only want errors from files found inside ``my_project`` we can do: + +.. prompt:: bash + + flake8 my_project + +And if we only want certain errors (e.g., ``E123``) from files in that +directory we can also do: + +.. prompt:: bash + + flake8 --select E123 my_project + +If you want to explore more options that can be passed on the command-line, +you can use the ``--help`` option: + +.. prompt:: bash + + flake8 --help + +And you should see something like: + +.. code:: + + Usage: flake8 [options] file file ... + + Options: + --version show program's version number and exit + -h, --help show this help message and exit + -v, --verbose Print more information about what is happening in + flake8. This option is repeatable and will increase + verbosity each time it is repeated. + -q, --quiet Report only file names, or nothing. This option is + repeatable. + --count Print total number of errors and warnings to standard + error and set the exit code to 1 if total is not + empty. + --diff Report changes only within line number ranges in the + unified diff provided on standard in by the user. + --exclude=patterns Comma-separated list of files or directories to + exclude.(Default: + .svn,CVS,.bzr,.hg,.git,__pycache__,.tox) + --filename=patterns Only check for filenames matching the patterns in this + comma-separated list. (Default: *.py) + --format=format Format errors according to the chosen formatter. + --hang-closing Hang closing bracket instead of matching indentation + of opening bracket's line. + --ignore=errors Comma-separated list of errors and warnings to ignore + (or skip). For example, ``--ignore=E4,E51,W234``. + (Default: E121,E123,E126,E226,E24,E704) + --max-line-length=n Maximum allowed line length for the entirety of this + run. (Default: 79) + --select=errors Comma-separated list of errors and warnings to enable. + For example, ``--select=E4,E51,W234``. (Default: ) + --disable-noqa Disable the effect of "# noqa". This will report + errors on lines with "# noqa" at the end. + --show-source Show the source generate each error or warning. + --statistics Count errors and warnings. + --enabled-extensions=ENABLED_EXTENSIONS + Enable plugins and extensions that are otherwise + disabled by default + --exit-zero Exit with status code "0" even if there are errors. + -j JOBS, --jobs=JOBS Number of subprocesses to use to run checks in + parallel. This is ignored on Windows. The default, + "auto", will auto-detect the number of processors + available to use. (Default: auto) + --output-file=OUTPUT_FILE + Redirect report to a file. + --append-config=APPEND_CONFIG + Provide extra config files to parse in addition to the + files found by Flake8 by default. These files are the + last ones read and so they take the highest precedence + when multiple files provide the same option. + --config=CONFIG Path to the config file that will be the authoritative + config source. This will cause Flake8 to ignore all + other configuration files. + --isolated Ignore all found configuration files. + --builtins=BUILTINS define more built-ins, comma separated + --doctests check syntax of the doctests + --include-in-doctest=INCLUDE_IN_DOCTEST + Run doctests only on these files + --exclude-from-doctest=EXCLUDE_FROM_DOCTEST + Skip these files when running doctests + + Installed plugins: pyflakes: 1.0.0, pep8: 1.7.0 |