From 41277ff965b9083d898ad8c2c990f7c119a8a1ae Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Mon, 20 Jun 2016 08:13:50 -0500 Subject: [PATCH] Use |Flake8| consistently throughout documentation --- docs/source/dev/formatters.rst | 11 ++--- docs/source/dev/index.rst | 4 +- docs/source/dev/plugin_parameters.rst | 22 ++++----- docs/source/dev/registering_plugins.rst | 12 ++--- docs/source/index.rst | 53 ++++++++++++++-------- docs/source/internal/checker.rst | 12 ++--- docs/source/internal/cli.rst | 4 +- docs/source/internal/contributing.rst | 42 ++++++++--------- docs/source/internal/formatters.rst | 6 +-- docs/source/internal/index.rst | 2 +- docs/source/internal/option_handling.rst | 57 ++++++++++++++---------- docs/source/internal/plugin_handling.rst | 20 ++++----- docs/source/internal/utils.rst | 14 +++--- docs/source/user/configuration.rst | 35 ++++++++------- docs/source/user/ignoring-errors.rst | 8 +--- docs/source/user/index.rst | 8 ++-- docs/source/user/invocation.rst | 16 +++---- docs/source/user/options.rst | 31 ++++++------- docs/source/user/python-api.rst | 2 +- 19 files changed, 192 insertions(+), 167 deletions(-) diff --git a/docs/source/dev/formatters.rst b/docs/source/dev/formatters.rst index 5beafda..480ada0 100644 --- a/docs/source/dev/formatters.rst +++ b/docs/source/dev/formatters.rst @@ -4,7 +4,7 @@ Developing a Formatting Plugin for Flake8 =========================================== -Flake8 allowed for custom formatting plugins in version +|Flake8| allowed for custom formatting plugins in version 3.0.0. Let's write a plugin together: .. code-block:: python @@ -17,11 +17,12 @@ Flake8 allowed for custom formatting plugins in version pass -We notice, as soon as we start, that we inherit from Flake8's +We notice, as soon as we start, that we inherit from |Flake8|'s :class:`~flake8.formatting.base.BaseFormatter` class. If we follow the :ref:`instructions to register a plugin ` and try to use -our example formatter, e.g., ``flake8 --format=example`` then Flake8 will fail -because we did not implement the ``format`` method. Let's do that next. +our example formatter, e.g., ``flake8 --format=example`` then +|Flake8| will fail because we did not implement the ``format`` method. +Let's do that next. .. code-block:: python @@ -34,7 +35,7 @@ because we did not implement the ``format`` method. Let's do that next. With that we're done. Obviously this isn't a very useful formatter, but it should highlight the simplicitly of creating a formatter with Flake8. If we wanted to instead create a formatter that aggregated the results and returned -XML, JSON, or subunit we could also do that. Flake8 interacts with the +XML, JSON, or subunit we could also do that. |Flake8| interacts with the formatter in two ways: #. It creates the formatter and provides it the options parsed from the diff --git a/docs/source/dev/index.rst b/docs/source/dev/index.rst index 4969395..9ef8138 100644 --- a/docs/source/dev/index.rst +++ b/docs/source/dev/index.rst @@ -2,8 +2,8 @@ Writing Plugins for Flake8 ============================ -Since Flake8 2.0, the Flake8 tool has allowed for extensions and custom -plugins. In Flake8 3.0, we're expanding that ability to customize and +Since |Flake8| 2.0, the |Flake8| tool has allowed for extensions and custom +plugins. In |Flake8| 3.0, we're expanding that ability to customize and extend **and** we're attempting to thoroughly document it. Some of the documentation in this section will reference third-party documentation to reduce duplication and to point you, the developer, towards diff --git a/docs/source/dev/plugin_parameters.rst b/docs/source/dev/plugin_parameters.rst index 9b074ec..527950c 100644 --- a/docs/source/dev/plugin_parameters.rst +++ b/docs/source/dev/plugin_parameters.rst @@ -4,15 +4,15 @@ Receiving Information For A Check Plugin ========================================== -Plugins to Flake8 have a great deal of information that they can request from -a :class:`~flake8.processor.FileProcessor` instance. Historically, Flake8 has -supported two types of plugins: +Plugins to |Flake8| have a great deal of information that they can request +from a :class:`~flake8.processor.FileProcessor` instance. Historically, +|Flake8| has supported two types of plugins: #. classes that accept parsed abstract syntax trees (ASTs) #. functions that accept a range of arguments -Flake8 now does not distinguish between the two types of plugins. Any plugin +|Flake8| now does not distinguish between the two types of plugins. Any plugin can accept either an AST or a range of arguments. Further, any plugin that has certain callable attributes can also register options and receive parsed options. @@ -21,8 +21,8 @@ options. Indicating Desired Data ======================= -Flake8 inspects the plugin's signature to determine what parameters it expects -using :func:`flake8.utils.parameters_for`. +|Flake8| inspects the plugin's signature to determine what parameters it +expects using :func:`flake8.utils.parameters_for`. :attr:`flake8.plugins.manager.Plugin.parameters` caches the values so that each plugin makes that fairly expensive call once per plugin. When processing a file, a plugin can ask for any of the following: @@ -56,7 +56,7 @@ Any plugin that has callable attributes ``provide_options`` and Your ``register_options`` function should expect to receive an instance of |OptionManager|. An |OptionManager| instance behaves very similarly to -:class:`optparse.OptionParser`. It, however, uses the layer that Flake8 has +:class:`optparse.OptionParser`. It, however, uses the layer that |Flake8| has developed on top of :mod:`optparse` to also handle configuration file parsing. :meth:`~flake8.options.manager.OptionManager.add_option` creates an |Option| which accepts the same parameters as :mod:`optparse` as well as three extra @@ -65,7 +65,7 @@ boolean parameters: - ``parse_from_config`` The command-line option should also be parsed from config files discovered - by Flake8. + by |Flake8|. .. note:: @@ -91,8 +91,8 @@ boolean parameters: allow a comma-separated list of paths. Each of these options works individually or can be combined. Let's look at a -couple examples from Flake8. In each example, we will have ``option_manager`` -which is an instance of |OptionManager|. +couple examples from |Flake8|. In each example, we will have +``option_manager`` which is an instance of |OptionManager|. .. code-block:: python @@ -143,7 +143,7 @@ documentation of :mod:`optparse`. Accessing Parsed Options ======================== -When a plugin has a callable ``provide_options`` attribute, Flake8 will call +When a plugin has a callable ``provide_options`` attribute, |Flake8| will call it and attempt to provide the |OptionManager| instance, the parsed options which will be an instance of :class:`optparse.Values`, and the extra arguments that were not parsed by the |OptionManager|. If that fails, we will just pass diff --git a/docs/source/dev/registering_plugins.rst b/docs/source/dev/registering_plugins.rst index 53b6dc4..5d01f99 100644 --- a/docs/source/dev/registering_plugins.rst +++ b/docs/source/dev/registering_plugins.rst @@ -4,7 +4,7 @@ Registering a Plugin with Flake8 ================================== -To register any kind of plugin with Flake8, you need: +To register any kind of plugin with |Flake8|, you need: #. A way to install the plugin (whether it is packaged on its own or as part of something else). In this section, we will use a ``setup.py`` @@ -15,9 +15,9 @@ To register any kind of plugin with Flake8, you need: #. A somewhat recent version of setuptools (newer than 0.7.0 but preferably as recent as you can attain). -Flake8 relies on functionality provided by setuptools called -`Entry Points`_. These allow any package to register a plugin with Flake8 via -that package's ``setup.py`` file. +|Flake8| relies on functionality provided by setuptools called +`Entry Points`_. These allow any package to register a plugin with |Flake8| +via that package's ``setup.py`` file. Let's presume that we already have our plugin written and it's in a module called ``flake8_example``. We might have a ``setup.py`` that looks something @@ -82,7 +82,7 @@ Note specifically these lines: We tell setuptools to register our entry point "X" inside the specific grouping of entry-points that flake8 should look in. -Flake8 presently looks at three groups: +|Flake8| presently looks at three groups: - ``flake8.extension`` @@ -90,7 +90,7 @@ Flake8 presently looks at three groups: - ``flake8.report`` -If your plugin is one that adds checks to Flake8, you will use +If your plugin is one that adds checks to |Flake8|, you will use ``flake8.extension``. If your plugin automatically fixes errors in code, you will use ``flake8.listen``. Finally, if your plugin performs extra report handling (formatting, filtering, etc.) it will use ``flake8.report``. diff --git a/docs/source/index.rst b/docs/source/index.rst index da383c6..68dc3fa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,18 +7,21 @@ Flake8: Your Tool For Style Guide Enforcement =============================================== +Quickstart +========== + .. _installation-guide: Installation -============ +------------ -To install Flake8, open an interactive shell and run: +To install |Flake8|, open an interactive shell and run: .. code:: python -m pip install flake8 -If you want Flake8 to be installed for your default Python installation, you +If you want |Flake8| to be installed for your default Python installation, you can instead use: .. code:: @@ -27,16 +30,16 @@ can instead use: .. note:: - It is **very** important to install Flake8 on the *correct* version of - Python for your needs. If you want Flake8 to properly parse new language + It is **very** important to install |Flake8| on the *correct* version of + Python for your needs. If you want |Flake8| to properly parse new language features in Python 3.5 (for example), you need it to be installed on 3.5 - for flake8 to understand those features. In many ways, Flake8 is tied to + for |Flake8| to understand those features. In many ways, Flake8 is tied to the version of Python on which it runs. -Quickstart -========== +Using Flake8 +------------ -To start using Flake8, open an interactive shell and run: +To start using |Flake8|, open an interactive shell and run: .. code:: @@ -46,7 +49,7 @@ To start using Flake8, open an interactive shell and run: .. note:: - If you have installed Flake8 on a particular version of Python (or on + If you have installed |Flake8| on a particular version of Python (or on several versions), it may be best to instead run ``python -m flake8``. @@ -55,20 +58,24 @@ If you only want to see the instances of a specific warning or error, you can .. code:: - flake8 --select path/to/code/ + flake8 --select E123,W503 path/to/code/ Alternatively, if you want to *ignore* only one specific warning or error: .. code:: - flake8 --ignore path/to/code/ + flake8 --ignore E24,W504 path/to/code/ Please read our user guide for more information about how to use and configure -Flake8. +|Flake8|. User Guide ========== +All users of |Flake8| should read this portion of the documentation. This +provides examples and documentation around |Flake8|'s assortment of options +and how to specify them on the command-line or in configuration files. + .. toctree:: :maxdepth: 2 @@ -77,13 +84,22 @@ User Guide Plugin Developer Guide ====================== +If you're maintaining a plugin for |Flake8| or creating a new one, you should +read this section of the documentation. It explains how you can write your +plugins and distribute them to others. + .. toctree:: :maxdepth: 2 dev/index -Developer Guide -=============== +Contributor Guide +================= + +If you are reading |Flake8|'s source code for fun or looking to contribute, +you should read this portion of the documentation. This is a mix of documenting +the internal-only interfaces |Flake8| and documenting reasoning for Flake8's +design. .. toctree:: :maxdepth: 2 @@ -98,9 +114,8 @@ Release Notes and History release-notes/index -Indices and tables -================== +General Indices +=============== * :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +* :ref:`Index of Documented Public Modules ` diff --git a/docs/source/internal/checker.rst b/docs/source/internal/checker.rst index e82e62f..19bcf7d 100644 --- a/docs/source/internal/checker.rst +++ b/docs/source/internal/checker.rst @@ -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 diff --git a/docs/source/internal/cli.rst b/docs/source/internal/cli.rst index bb8f774..f203125 100644 --- a/docs/source/internal/cli.rst +++ b/docs/source/internal/cli.rst @@ -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. diff --git a/docs/source/internal/contributing.rst b/docs/source/internal/contributing.rst index 2406e9a..06e6ec3 100644 --- a/docs/source/internal/contributing.rst +++ b/docs/source/internal/contributing.rst @@ -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. diff --git a/docs/source/internal/formatters.rst b/docs/source/internal/formatters.rst index b371307..c58189b 100644 --- a/docs/source/internal/formatters.rst +++ b/docs/source/internal/formatters.rst @@ -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 diff --git a/docs/source/internal/index.rst b/docs/source/internal/index.rst index 81efa2c..d4d05ac 100644 --- a/docs/source/internal/index.rst +++ b/docs/source/internal/index.rst @@ -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 diff --git a/docs/source/internal/option_handling.rst b/docs/source/internal/option_handling.rst index 1a5b31f..74ecb76 100644 --- a/docs/source/internal/option_handling.rst +++ b/docs/source/internal/option_handling.rst @@ -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 `` 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 diff --git a/docs/source/internal/plugin_handling.rst b/docs/source/internal/plugin_handling.rst index 65b2fa1..9af3182 100644 --- a/docs/source/internal/plugin_handling.rst +++ b/docs/source/internal/plugin_handling.rst @@ -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:: diff --git a/docs/source/internal/utils.rst b/docs/source/internal/utils.rst index 573938c..1b2bb1c 100644 --- a/docs/source/internal/utils.rst +++ b/docs/source/internal/utils.rst @@ -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 diff --git a/docs/source/user/configuration.rst b/docs/source/user/configuration.rst index 6085bcd..439aeae 100644 --- a/docs/source/user/configuration.rst +++ b/docs/source/user/configuration.rst @@ -4,7 +4,7 @@ Configuring Flake8 ==================== -Once you have learned how to :ref:`invoke ` Flake8, you will soon +Once you have learned how to :ref:`invoke ` |Flake8|, you will soon want to learn how to configure it so you do not have to specify the same options every time you use it. @@ -24,7 +24,7 @@ Remember that you want to specify certain options without writing Configuration Locations ======================= -Flake8 supports storing its configuration in the following places: +|Flake8| supports storing its configuration in the following places: - Your top-level user directory @@ -34,7 +34,7 @@ Flake8 supports storing its configuration in the following places: "User" Configuration -------------------- -Flake8 allows a user to use "global" configuration file to store preferences. +|Flake8| allows a user to use "global" configuration file to store preferences. The user configuration file is expected to be stored somewhere in the user's "home" directory. @@ -44,7 +44,7 @@ The user configuration file is expected to be stored somewhere in the user's - On Linux and other Unix like systems (including OS X) we will look in ``~/``. -Note that Flake8 looks for ``~\.flake8`` on Windows and ``~/.config/flake8`` +Note that |Flake8| looks for ``~\.flake8`` on Windows and ``~/.config/flake8`` on Linux and other Unix systems. User configuration files use the same syntax as Project Configuration files. @@ -54,8 +54,8 @@ Keep reading to see that syntax. Project Configuration --------------------- -Flake8 is written with the understanding that people organize projects into -sub-directories. Let's take for example Flake8's own project structure +|Flake8| is written with the understanding that people organize projects into +sub-directories. Let's take for example |Flake8|'s own project structure .. code:: @@ -81,10 +81,10 @@ sub-directories. Let's take for example Flake8's own project structure In the top-level ``flake8`` directory (which contains ``docs``, ``flake8``, and ``tests``) there's also ``tox.ini`` and ``setup.cfg`` files. In our case, -we keep our Flake8 configuration in ``tox.ini``. Regardless of whether you +we keep our |Flake8| configuration in ``tox.ini``. Regardless of whether you keep your config in ``.flake8``, ``setup.cfg``, or ``tox.ini`` we expect you -to use INI to configure Flake8 (since each of these files already uses INI -as a format). This means that any Flake8 configuration you wish to set needs +to use INI to configure |Flake8| (since each of these files already uses INI +as a format). This means that any |Flake8| configuration you wish to set needs to be in the ``flake8`` section, which means it needs to start like so: .. code-block:: ini @@ -100,11 +100,11 @@ be named in either of two ways: .. note:: - Not every Flake8 command-line option can be specified in the configuration - file. See :ref:`our list of options ` to determine which - options will be parsed from the configuration files. + Not every |Flake8| command-line option can be specified in the + configuration file. See :ref:`our list of options ` to + determine which options will be parsed from the configuration files. -Let's actually look at Flake8's own configuration section: +Let's actually look at |Flake8|'s own configuration section: .. code-block:: ini @@ -163,14 +163,14 @@ This would allow us to add comments for why we're excluding items, e.g., :mod:`configparser` backport from PyPI. That backport enables us to support this behaviour on all supported versions of Python. - Please do **not** open issues about this dependency to Flake8. + Please do **not** open issues about this dependency to |Flake8|. .. note:: You can also specify ``--max-complexity`` as ``max_complexity = 10``. This is also useful if you have a long list of error codes to ignore. Let's -look at a portion of OpenStack's Swift project configuration: +look at a portion of OpenStack's Swift `project configuration`_: .. code-block:: ini @@ -220,5 +220,8 @@ They use the comments to describe the check but they could also write this as: H501 Or they could use each comment to describe **why** they've ignored the check. -:program:`Flake8` knows how to parse these lists and will appropriatey handle +|Flake8| knows how to parse these lists and will appropriatey handle these situations. + +.. _project configuration: + https://github.com/openstack/swift/blob/3944d820387f08372c1a29444f4af7d8e6090ae9/tox.ini#L66..L81 diff --git a/docs/source/user/ignoring-errors.rst b/docs/source/user/ignoring-errors.rst index b9af8a8..ff37c4a 100644 --- a/docs/source/user/ignoring-errors.rst +++ b/docs/source/user/ignoring-errors.rst @@ -55,7 +55,7 @@ then those will be reported. .. note:: - If we ever want to disable Flake8 respecting ``# noqa`` comments, we can + If we ever want to disable |Flake8| respecting ``# noqa`` comments, we can can refer to :option:`flake8 --disable-noqa`. If we instead had more than one error that we wished to ignore, we could @@ -84,11 +84,7 @@ file: The former is the **recommended** way of ignoring entire files. By using our exclude list, we can include it in our configuration file and have one central -place to find what files aren't included in Flake8 checks. The latter has the +place to find what files aren't included in |Flake8| checks. The latter has the benefit that when we run |Flake8| with :option:`flake8 --disable-noqa` all of the errors in that file will show up without having to modify our configuration. Both exist so we can choose which is better for us. - - -.. replacements -.. |Flake8| replace:: :program:`Flake8` diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst index 4644efc..255ec27 100644 --- a/docs/source/user/index.rst +++ b/docs/source/user/index.rst @@ -2,7 +2,7 @@ Using Flake8 ============== -Flake8 can be used in many ways. A few: +|Flake8| can be used in many ways. A few: - invoked on the command-line @@ -10,12 +10,12 @@ Flake8 can be used in many ways. A few: - called by Git or Mercurial on or around committing -This guide will cover all of these and the nuances for using Flake8. +This guide will cover all of these and the nuances for using |Flake8|. .. note:: - This portion of Flake8's documentation does not cover installation. See - the :ref:`installation-guide` section for how to install Flake8. + This portion of |Flake8|'s documentation does not cover installation. See + the :ref:`installation-guide` section for how to install |Flake8|. .. toctree:: :maxdepth: 2 diff --git a/docs/source/user/invocation.rst b/docs/source/user/invocation.rst index ef763ae..5c92ca3 100644 --- a/docs/source/user/invocation.rst +++ b/docs/source/user/invocation.rst @@ -4,16 +4,16 @@ Invoking Flake8 ================= -Once you have :ref:`installed ` Flake8, you can begin -using it. Most of the time, you will be able to generically invoke Flake8 +Once you have :ref:`installed ` |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 +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: @@ -27,15 +27,15 @@ Or python3.5 -m flake8 -Since that will tell the correct version of Python to run 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 + 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: +It is also possible to specify command-line options directly to |Flake8|: .. prompt:: bash @@ -53,7 +53,7 @@ Or From now on, we'll simply use ``flake8`` and assume that the user knows they can instead use ``python -m flake8`` instead. -It's also possible to narrow what Flake8 will try to check by specifying +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 subdirectories which have python files (and may have more sub-directories) called ``my_project``. Then if diff --git a/docs/source/user/options.rst b/docs/source/user/options.rst index 7f79e61..acaa67c 100644 --- a/docs/source/user/options.rst +++ b/docs/source/user/options.rst @@ -29,7 +29,7 @@ .. option:: --version - Show :program:`Flake8`\ 's version as well as the versions of all plugins + Show |Flake8|'s version as well as the versions of all plugins installed. Command-line usage: @@ -43,7 +43,7 @@ .. option:: -h, --help - Show a description of how to use :program:`Flake8` and its options. + Show a description of how to use |Flake8| and its options. Command-line usage: @@ -57,7 +57,7 @@ .. option:: -v, --verbose - Increase the verbosity of Flake8's output. Each time you specify + Increase the verbosity of |Flake8|'s output. Each time you specify it, it will print more and more information. Command-line example: @@ -77,7 +77,7 @@ .. option:: -q, --quiet - Decrease the verbosity of Flake8's output. Each time you specify it, + Decrease the verbosity of |Flake8|'s output. Each time you specify it, it will print less and less information. Command-line example: @@ -286,7 +286,7 @@ Specify a list of codes to ignore. The list is expected to be comma-separated, and does not need to specify an error code exactly. - Since Flake8 3.0, this **can** be combined with :option:`--select`. See + Since |Flake8| 3.0, this **can** be combined with :option:`--select`. See :option:`--select` for more information. For example, if you wish to only ignore ``W234``, then you can specify @@ -349,7 +349,7 @@ .. option:: --select= - Specify the list of error codes you wish Flake8 to report. Similarly to + Specify the list of error codes you wish |Flake8| to report. Similarly to :option:`--ignore`. You can specify a portion of an error code to get all that start with that string. For example, you can use ``E``, ``E4``, ``E43``, and ``E431``. @@ -370,7 +370,7 @@ flake8 --select=E --ignore=E432 dir/ This will report all codes that start with ``E``, but ignore ``E432`` - specifically. This is more flexibly than the Flake8 2.x and 1.x used + specifically. This is more flexibly than the |Flake8| 2.x and 1.x used to be. This **can** be specified in config files. @@ -453,7 +453,7 @@ Enable off-by-default extensions. - Plugins to Flake8 have the option of registering themselves as + Plugins to |Flake8| have the option of registering themselves as off-by-default. These plugins effectively add themselves to the default ignore list. @@ -479,9 +479,9 @@ .. option:: --exit-zero - Force Flake8 to use the exit status code 0 even if there are errors. + Force |Flake8| to use the exit status code 0 even if there are errors. - By default Flake8 will exit with a non-zero integer if there are errors. + By default |Flake8| will exit with a non-zero integer if there are errors. Command-line example: @@ -514,7 +514,7 @@ .. option:: --jobs= - Specify the number of subprocesses that Flake8 will use to run checks in + Specify the number of subprocesses that |Flake8| will use to run checks in parallel. .. note:: @@ -566,7 +566,7 @@ .. option:: --append-config= Provide extra config files to parse in after and in addition to the files - that Flake8 found on its own. Since these files are the last ones read + that |Flake8| found on its own. Since these files are the last ones read into the Configuration Parser, so it has the highest precedence if it provides an option specified in another config file. @@ -582,7 +582,8 @@ .. option:: --config= Provide a path to a config file that will be the only config file read and - used. This will cause Flake8 to ignore all other config files that exist. + used. This will cause |Flake8| to ignore all other config files that + exist. Command-line example: @@ -595,7 +596,7 @@ .. option:: --isolated - Ignore any config files and use Flake8 as if there were no config files + Ignore any config files and use |Flake8| as if there were no config files found. Command-line example: @@ -710,7 +711,7 @@ .. option:: --benchmark - Collect and print benchmarks for this run of Flake8. This aggregates the + Collect and print benchmarks for this run of |Flake8|. This aggregates the total number of: - tokens diff --git a/docs/source/user/python-api.rst b/docs/source/user/python-api.rst index 2e2a16e..214565d 100644 --- a/docs/source/user/python-api.rst +++ b/docs/source/user/python-api.rst @@ -2,7 +2,7 @@ Public Python API =================== -Flake8 3.0.0 presently does not have a public, stable Python API. +|Flake8| 3.0.0 presently does not have a public, stable Python API. When it does it will be located in :mod:`flake8.api` and that will be documented here.