diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/internal/option_handling.rst | 64 |
1 files changed, 63 insertions, 1 deletions
diff --git a/docs/source/internal/option_handling.rst b/docs/source/internal/option_handling.rst index f81a4be..01b3862 100644 --- a/docs/source/internal/option_handling.rst +++ b/docs/source/internal/option_handling.rst @@ -117,7 +117,64 @@ extra arguments we highlighted above. Configuration File Management ----------------------------- -.. todo:: Add notes about Config 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. +As part of managing this ourselves, we decided to change management/discovery +for 3.0.0. We have done the following: + +- User files (files stored in a user's home directory or in the XDG directory + inside their home directory) are the first files read. For example, if the + user has a ``~/.flake8`` file, we will read that first. + +- Project files (files stored in the current directory) are read next and + merged on top of the user file. In other words, configuration in project + files takes precedence over configuration in user files. + +- **New in 3.0.0** The user can specify ``--append-config <path-to-file>`` + repeatedly to include extra configuration files that should be read and + 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 + where pep8 would simply merge this configuration file into the configuration + generated by user and project files (where this takes precedence). + +- **New in 3.0.0** The user can specify ``--isolated`` to disable + configuration via discovered configuration files. + +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). + +Configuration file discovery is managed by the +:class:`~flake8.options.config.ConfigFileFinder` object. This object needs to +know information about the program's name, any extra arguments passed to it, +and any configuration files that should be appended to the list of discovered +files. It provides methods for finding the files and similiar methods for +parsing those fles. For example, it provides +:meth:`~flake8.options.config.ConfigFileFinder.local_config_files` to find +known local config files (and append the extra configuration files) and it +also provides :meth:`~flake8.options.config.ConfigFileFinder.local_configs` +to parse those configuration files. + +.. note:: ``local_config_files`` also filters out non-existent files. + +Configuration file merging and managemnt is controlled by the +:class:`~flake8.options.config.MergedConfigParser`. This requires the instance +of :class:`~flake8.options.manager.OptionManager` that the program is using, +the list of appended config files, and the list of extra arguments. + +.. todo:: Describe how the MergedConfigParser parses and merges config options + +.. _66 lines of very terse python: + https://github.com/PyCQA/pep8/blob/b8088a2b6bc5b76bece174efad877f764529bc74/pep8.py#L1981..L2047 API Documentation ----------------- @@ -129,5 +186,10 @@ API Documentation :members: :special-members: +.. autoclass:: flake8.options.config.ConfigFileFinder + :members: + :special-members: + .. autoclass:: flake8.options.config.MergedConfigParser :members: + :special-members: |