From 4cf48b9b772c558363340d64bacb35a867c945c6 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Wed, 27 Jan 2016 21:32:40 -0600 Subject: [PATCH] Add documentation about option aggregation Add logging around default ignore lists --- docs/source/internal/option_handling.rst | 34 ++++++++++++++++++++++-- flake8/options/aggregator.py | 20 +++++++++++++- 2 files changed, 51 insertions(+), 3 deletions(-) diff --git a/docs/source/internal/option_handling.rst b/docs/source/internal/option_handling.rst index 01b3862..8ab1911 100644 --- a/docs/source/internal/option_handling.rst +++ b/docs/source/internal/option_handling.rst @@ -169,9 +169,37 @@ to parse those configuration 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. +the list of appended config files, and the list of extra arguments. This +object is currently the sole user of the +:class:`~flake8.options.config.ConfigFileFinder` object. It appropriately +initializes the object and uses it in each of -.. todo:: Describe how the MergedConfigParser parses and merges config options +- :meth:`~flake8.options.config.MergedConfigParser.parse_cli_config` +- :meth:`~flake8.options.config.MergedConfigParser.parse_local_config` +- :meth:`~flake8.options.config.MergedConfigParser.parse_user_config` + +Finally, +:meth:`~flake8.options.config.MergedConfigParser.merge_user_and_local_config` +takes the user and local configuration files that are parsed by +:meth:`~flake8.options.config.MergedConfigParser.parse_local_config` and +:meth:`~flake8.options.config.MergedConfigParser.parse_user_config`. The +main usage of the ``MergedConfigParser`` is in +:func:`~flake8.options.aggregator.aggregate_options`. + +Aggregating Configuration File and Command Line Arguments +--------------------------------------------------------- + +:func:`~flake8.options.aggregator.aggregate_options` accepts an instance of +:class:`~flake8.options.maanger.OptionManager` and does the work to parse the +command-line arguments passed by the user necessary for creating an instance +of :class:`~flake8.options.config.MergedConfigParser`. + +After parsing the configuration file, we determine the default ignore list. We +use the defaults from the OptionManager and update those with the parsed +configuration files. Finally we parse the user-provided options one last time +using the option defaults and configuration file values as defaults. The +parser merges on the command-line specified arguments for us so we have our +final, definitive, aggregated options. .. _66 lines of very terse python: https://github.com/PyCQA/pep8/blob/b8088a2b6bc5b76bece174efad877f764529bc74/pep8.py#L1981..L2047 @@ -179,6 +207,8 @@ the list of appended config files, and the list of extra arguments. API Documentation ----------------- +.. autofunction:: flake8.options.aggregator.aggregate_options + .. autoclass:: flake8.options.manager.Option :members: __init__, normalize, to_optparse diff --git a/flake8/options/aggregator.py b/flake8/options/aggregator.py index e12952a..5c02730 100644 --- a/flake8/options/aggregator.py +++ b/flake8/options/aggregator.py @@ -12,7 +12,22 @@ LOG = logging.getLogger(__name__) def aggregate_options(manager, arglist=None, values=None): - """Function that aggregates the CLI and Config options.""" + """Aggregate and merge CLI and config file options. + + :param flake8.option.manager.OptionManager manager: + The instance of the OptionManager that we're presently using. + :param list arglist: + The list of arguments to pass to ``manager.parse_args``. In most cases + this will be None so ``parse_args`` uses ``sys.argv``. This is mostly + available to make testing easier. + :param optparse.Values values: + Previously parsed set of parsed options. + :returns: + Tuple of the parsed options and extra arguments returned by + ``manager.parse_args``. + :rtype: + tuple(optparse.Values, list) + """ # Get defaults from the option parser default_values, _ = manager.parse_args([], values=values) # Get original CLI values so we can find additional config file paths and @@ -34,8 +49,11 @@ def aggregate_options(manager, arglist=None, values=None): # Extend the default ignore value with the extended default ignore list, # registered by plugins. extended_default_ignore = manager.extended_default_ignore.copy() + LOG.debug('Extended default ignore list: %s', + list(extended_default_ignore)) extended_default_ignore.update(default_values.ignore) default_values.ignore = list(extended_default_ignore) + LOG.debug('Merged default ignore list: %s', default_values.ignore) # Merge values parsed from config onto the default values returned for config_name, value in parsed_config.items():