pre-commit/flake8
1
0
Fork 0
mirror of https://github.com/PyCQA/flake8.git synced 2026-04-06 21:16:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Use |Flake8| consistently throughout documentation

Browse source
This commit is contained in:
Ian Cordasco 2016-06-20 08:13:50 -05:00
parent 57ac6ab699
commit 41277ff965
No known key found for this signature in database
GPG key ID: 656D3395E4A9791A
19 changed files with 192 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/source/internal/checker.rst
View file

@ -2,13 +2,13 @@
How Checks are Run
====================
In Flake8 2.x, Flake8 delegated check running to pep8. In 3.0 flake8 takes
on that responsibility. This has allowed for simpler
In |Flake8| 2.x, |Flake8| delegated check running to pep8. In 3.0 |Flake8|
takes on that responsibility. This has allowed for simpler
handling of the ``--jobs`` parameter (using :mod:`multiprocessing`) and
simplified our fallback if something goes awry with concurency.
At the lowest level we have a |FileChecker|. Instances of |FileChecker| are
created for *each* file to be analyzed by Flake8. Each instance, has a copy of
all of the plugins registered with setuptools in the ``flake8.extension``
created for *each* file to be analyzed by |Flake8|. Each instance, has a copy
of all of the plugins registered with setuptools in the ``flake8.extension``
entry-point group.
The |FileChecker| instances are managed by an instance of |Manager|. The
@ -22,8 +22,8 @@ excluded.
Processing Files
----------------
Unfortunately, since Flake8 took over check running from pep8/pycodestyle, it
also had to take over parsing and processing files for the checkers
Unfortunately, since |Flake8| took over check running from pep8/pycodestyle,
it also had to take over parsing and processing files for the checkers
to use. Since it couldn't reuse pycodestyle's functionality (since it did not
separate cleanly the processing from check running) that function was isolated
into the :class:`~flake8.processor.FileProcessor` class. We moved

4
docs/source/internal/cli.rst
View file

@ -1,7 +1,7 @@
Command Line Interface
======================
The command line interface of Flake8 is modeled as an application via
The command line interface of |Flake8| is modeled as an application via
:class:`~flake8.main.cli.Application`. When a user runs ``flake8`` at their
command line, :func:`~flake8.main.cli.main` is run which handles
management of the application.
@ -10,7 +10,7 @@ User input is parsed *twice* to accomodate logging and verbosity options
passed by the user as early as possible.
This is so as much logging can be produced as possible.
The default flake8 options are registered by
The default |Flake8| options are registered by
:func:`~flake8.main.options.register_default_options`. Trying to register
these options in plugins will result in errors.

42
docs/source/internal/contributing.rst
View file

@ -2,7 +2,7 @@
Contributing to Flake8
========================
There are many ways to contriubte to Flake8, and we encourage them all:
There are many ways to contriubte to |Flake8|, and we encourage them all:
- contributing bug reports and feature requests
@ -18,7 +18,7 @@ reassure you that any help you can provide *is* valuable.
Code of Conduct
===============
Flake8 adheres to the `Python Code Quality Authority's Code of Conduct`_.
|Flake8| adheres to the `Python Code Quality Authority's Code of Conduct`_.
Any violations of the Code of Conduct should be reported to Ian Cordasco
(graffatcolmingov [at] gmail [dot] com).
@ -26,7 +26,7 @@ Any violations of the Code of Conduct should be reported to Ian Cordasco
Setting Up A Development Environment
====================================
To contribute to Flake8's development, you simply need:
To contribute to |Flake8|'s development, you simply need:
- Python (one of the versions we support)
@ -50,29 +50,29 @@ To contribute to Flake8's development, you simply need:
Filing a Bug
============
When filing a bug against Flake8, please fill out the issue template as it is
provided to you by `GitLab`_. If your bug is in reference to one of the
checks that Flake8 reports by default, please do not report them to Flake8
unless Flake8 is doing something to prevent the check from running or you
have some reason to believe Flake8 is inhibiting the effectiveness of the
When filing a bug against |Flake8|, please fill out the issue template as it
is provided to you by `GitLab`_. If your bug is in reference to one of the
checks that |Flake8| reports by default, please do not report them to |Flake8|
unless |Flake8| is doing something to prevent the check from running or you
have some reason to believe |Flake8| is inhibiting the effectiveness of the
check.
**Please search for closed and open bug reports before opening new ones.**
All bug reports about checks should go to their respective projects:
- Check codes starting with ``E`` and ``W`` should be reported to
- Error codes starting with ``E`` and ``W`` should be reported to
`pycodestyle`_.
- Check codes starting with ``F`` should be reported to `pyflakes`_
- Error codes starting with ``F`` should be reported to `pyflakes`_
- Check codes starting with ``C`` should be reported to `mccabe`_
- Error codes starting with ``C`` should be reported to `mccabe`_
Requesting a New Feature
========================
When requesting a new feature in Flake8, please fill out the issue template.
When requesting a new feature in |Flake8|, please fill out the issue template.
Please also note if there are any existing alternatives to your new feature
either via plugins, or combining command-line options. Please provide example
use cases. For example, do not ask for a feature like this:
@ -81,8 +81,8 @@ use cases. For example, do not ask for a feature like this:
Instead ask:
I need Flake8 to frobulate these files because my team expects them to
frobulated but Flake8 currently does not frobulate them. We tried using
I need |Flake8| to frobulate these files because my team expects them to
frobulated but |Flake8| currently does not frobulate them. We tried using
``--filename`` but we could not create a pattern that worked.
The more you explain about *why* you need a feature, the more likely we are to
@ -92,11 +92,11 @@ understand your needs and help you to the best of our ability.
Contributing Documentation
==========================
To contribute to Flake8's documentation, you should first familiarize yourself
with reStructuredText and Sphinx. For the most part, you should be fine
following the structure and style of the rest of Flake8's documentation.
To contribute to |Flake8|'s documentation, you might want to first read a
little about reStructuredText or Sphinx. For the most part, you should be fine
following the structure and style of the rest of |Flake8|'s documentation.
All of Flake8's documentation is written in reStructuredText and rendered by
All of |Flake8|'s documentation is written in reStructuredText and rendered by
Sphinx. The source (reStructuredText) lives in ``docs/source/``. To build
the documentation the way our Continuous Integration does, run:
@ -129,7 +129,7 @@ documentation generation and refresh the documentation you're working on.
Contributing Code
=================
Flake8 development happens on `GitLab`_. Code contributions should be
|Flake8| development happens on `GitLab`_. Code contributions should be
submitted there.
Merge requests should:
@ -170,12 +170,12 @@ When reviewing other people's merge requests and issues, please be
else. We strive for professional code reviews that do not insult the
contributor's intelligence or impugn their character. The code review
should be focused on the code, it's effectiveness, and whether it is
appropriate for Flake8.
appropriate for |Flake8|.
If you have the ability to edit an issue or merge request's labels, please do
so to make search and prioritization easier.
Flake8 uses milestones with both issues and merge requests. This provides
|Flake8| uses milestones with both issues and merge requests. This provides
direction for other contributors about when an issue or merge request will be
delivered.

6
docs/source/internal/formatters.rst
View file

@ -2,12 +2,12 @@
Built-in Formatters
=====================
By default Flake8 has two formatters built-in, ``default`` and ``pylint``.
By default |Flake8| has two formatters built-in, ``default`` and ``pylint``.
These correspond to two classes |DefaultFormatter| and |PylintFormatter|.
In Flake8 2.0, pep8 handled formatting of errors and also allowed users to
In |Flake8| 2.0, pep8 handled formatting of errors and also allowed users to
specify an arbitrary format string as a parameter to ``--format``. In order
to allow for this backwards compatibility, Flake8 3.0 made two choices:
to allow for this backwards compatibility, |Flake8| 3.0 made two choices:
#. To not limit a user's choices for ``--format`` to the format class names

2
docs/source/internal/index.rst
View file

@ -2,7 +2,7 @@
Exploring Flake8's Internals
==============================
While writing Flake8 3.0, the developers attempted to capture some reasoning
While writing |Flake8| 3.0, the developers attempted to capture some reasoning
and decision information in internal documentation meant for future developers
and maintaners. Most of this information is unnecessary for users and plugin
developers. Some of it, however, is linked to from the plugin development

57
docs/source/internal/option_handling.rst
View file

@ -4,12 +4,12 @@ Option and Configuration Handling
Option Management
-----------------
Command-line options are often also set in configuration files for Flake8.
Command-line options are often also set in configuration files for |Flake8|.
While not all options are meant to be parsed from configuration files, many
default options are also parsed from configuration files as well as
most plugin options.
In Flake8 2, plugins received a :class:`optparse.OptionParser` instance and
In |Flake8| 2, plugins received a :class:`optparse.OptionParser` instance and
called :meth:`optparse.OptionParser.add_option` to register options. If the
plugin author also wanted to have that option parsed from config files they
also had to do something like:
@ -22,13 +22,13 @@ also had to do something like:
This was previously undocumented and led to a lot of confusion about why
registered options were not automatically parsed from configuration files.
Since Flake8 3 was rewritten from scratch, we decided to take a different
Since |Flake8| 3 was rewritten from scratch, we decided to take a different
approach to configuration file parsing. Instead of needing to know about an
undocumented attribute that pep8 looks for, Flake8 3 now accepts a parameter
undocumented attribute that pep8 looks for, |Flake8| 3 now accepts a parameter
to ``add_option``, specifically ``parse_from_config`` which is a boolean
value.
Flake8 does this by creating its own abstractions on top of :mod:`optparse`.
|Flake8| does this by creating its own abstractions on top of :mod:`optparse`.
The first abstraction is the :class:`flake8.options.manager.Option` class. The
second is the :class:`flake8.options.manager.OptionManager`. In fact, we add
three new parameters:
@ -49,14 +49,22 @@ example, let's consider a user's list of ignored error codes for a project:
[flake8]
ignore =
E111, # Reasoning
E711, # Reasoning
E712, # Reasoning
E121, # Reasoning
E122, # Reasoning
E123, # Reasoning
E131, # Reasoning
E251 # Reasoning
# Reasoning
E111,
# Reasoning
E711,
# Reasoning
E712,
# Reasoning
E121,
# Reasoning
E122,
# Reasoning
E123,
# Reasoning
E131,
# Reasoning
E251
It makes sense here to allow users to specify the value this way, but, the
standard libary's :class:`configparser.RawConfigParser` class does returns a
@ -67,8 +75,8 @@ string that looks like
"\nE111, \nE711, \nE712, \nE121, \nE122, \nE123, \nE131, \nE251 "
This means that a typical call to :meth:`str.split` with ``','`` will not be
sufficient here. Telling Flake8 that something is a comma-separated list
(e.g., ``comma_separated_list=True``) will handle this for you. Flake8 will
sufficient here. Telling |Flake8| that something is a comma-separated list
(e.g., ``comma_separated_list=True``) will handle this for you. |Flake8| will
return:
.. code-block:: python
@ -117,10 +125,11 @@ extra arguments we highlighted above.
Configuration File Management
-----------------------------
In Flake8 2, configuration file discovery and management was handled by pep8.
In pep8's 1.6 release series, it drastically broke how discovery and merging
worked (as a result of trying to improve it). To avoid a dependency breaking
Flake8 again in the future, we have created our own discovery and management.
In |Flake8| 2, configuration file discovery and management was handled by
pep8. In pep8's 1.6 release series, it drastically broke how discovery and
merging worked (as a result of trying to improve it). To avoid a dependency
breaking |Flake8| again in the future, we have created our own discovery and
management.
As part of managing this ourselves, we decided to change management/discovery
for 3.0.0. We have done the following:
@ -137,7 +146,7 @@ for 3.0.0. We have done the following:
take precedence over user and project files.
- **New in 3.0.0** The user can specify ``--config <path-to-file>`` to so this
file is the only configuration file used. This is a change from Flake8 2
file is the only configuration file used. This is a change from |Flake8| 2
where pep8 would simply merge this configuration file into the configuration
generated by user and project files (where this takes precedence).
@ -148,10 +157,10 @@ To facilitate the configuration file management, we've taken a different
approach to discovery and management of files than pep8. In pep8 1.5, 1.6, and
1.7 configuration discovery and management was centralized in `66 lines of
very terse python`_ which was confusing and not very explicit. The terseness
of this function (Flake8's authors believe) caused the confusion and problems
with pep8's 1.6 series. As such, Flake8 has separated out discovery,
management, and merging into a module to make reasoning about each of these
pieces easier and more explicit (as well as easier to test).
of this function (|Flake8|'s authors believe) caused the confusion and
problems with pep8's 1.6 series. As such, |Flake8| has separated out
discovery, management, and merging into a module to make reasoning about each
of these pieces easier and more explicit (as well as easier to test).
Configuration file discovery is managed by the
:class:`~flake8.options.config.ConfigFileFinder` object. This object needs to

20
docs/source/internal/plugin_handling.rst
View file

@ -4,8 +4,8 @@ Plugin Handling
Plugin Management
-----------------
Flake8 3.0 added support for two other plugins besides those which define new
checks. It now supports:
|Flake8| 3.0 added support for two other plugins besides those which define
new checks. It now supports:
- extra checks
@ -13,7 +13,7 @@ checks. It now supports:
- listeners to auto-correct violations of checks
To facilitate this, Flake8 needed a more mature way of managing plugins.
To facilitate this, |Flake8| needed a more mature way of managing plugins.
Thus, we developed the |PluginManager| which accepts a namespace and will load
the plugins for that namespace. A |PluginManager| creates and manages many
|Plugin| instances.
@ -72,21 +72,21 @@ existing packages on PyPI allowed for storing data on each node of the trie,
it was left up to write our own as :class:`~flake8.plugins._trie.Trie`. On
top of that we layer our :class:`~flake8.plugins.notifier.Notifier` class.
Now when Flake8 receives an error or warning, we can easily call the
Now when |Flake8| receives an error or warning, we can easily call the
:meth:`~flake8.plugins.notifier.Notifier.notify` method and let plugins act on
that knowledge.
Default Plugins
---------------
Finally, Flake8 has always provided its own plugin shim for Pyflakes. As part
of that we carry our own shim in-tree and now store that in
Finally, |Flake8| has always provided its own plugin shim for Pyflakes. As
part of that we carry our own shim in-tree and now store that in
:mod:`flake8.plugins.pyflakes`.
Flake8 also registers plugins for pep8. Each check in pep8 requires different
parameters and it cannot easily be shimmed together like Pyflakes was. As
such, plugins have a concept of a "group". If you look at our :file:`setup.py`
you will see that we register pep8 checks roughly like so:
|Flake8| also registers plugins for pep8. Each check in pep8 requires
different parameters and it cannot easily be shimmed together like Pyflakes
was. As such, plugins have a concept of a "group". If you look at our
:file:`setup.py` you will see that we register pep8 checks roughly like so:
.. code::

14
docs/source/internal/utils.rst
View file

@ -2,7 +2,7 @@
Utility Functions
===================
Flake8 has a few utility functions that it uses internally.
|Flake8| has a few utility functions that it uses internally.
.. warning::
@ -39,8 +39,8 @@ And converts it to a list that looks as follows
["E121", "W123", "F904"]
This function helps normalize any kind of comma-separated input you or Flake8
might receive. This is most helpful when taking advantage of Flake8's
This function helps normalize any kind of comma-separated input you or |Flake8|
might receive. This is most helpful when taking advantage of |Flake8|'s
additional parameters to :class:`~flake8.options.manager.Option`.
.. autofunction:: flake8.utils.normalize_path
@ -74,11 +74,11 @@ Python we're using can actually use multiprocessing on Windows.
Another helpful function that is named only to be explicit given it is a very
trivial check, this checks if the user specified ``-`` in their arguments to
Flake8 to indicate we should read from stdin.
|Flake8| to indicate we should read from stdin.
.. autofunction:: flake8.utils.filenames_from
When provided an argument to Flake8, we need to be able to traverse
When provided an argument to |Flake8|, we need to be able to traverse
directories in a convenient manner. For example, if someone runs
.. code::
@ -103,7 +103,7 @@ function abstracts that logic away with a little extra logic.
.. autofunction:: flake8.utils.parameters_for
Flake8 analyzes the parameters to plugins to determine what input they are
|Flake8| analyzes the parameters to plugins to determine what input they are
expecting. Plugins may expect one of the following:
- ``physical_line`` to receive the line as it appears in the file
@ -120,7 +120,7 @@ argument so we can check the parameters of the plugin consistently.
.. autofunction:: flake8.utils.parse_unified_diff
To handle usage of :option:`flake8 --diff`, Flake8 needs to be able
To handle usage of :option:`flake8 --diff`, |Flake8| needs to be able
to parse the name of the files in the diff as well as the ranges indicated the
sections that have been changed. This function either accepts the diff as an
argument or reads the diff from standard-in. It then returns a dictionary with