diff --git a/docs/source/internal/formatters.rst b/docs/source/internal/formatters.rst index caa5718..d54cf87 100644 --- a/docs/source/internal/formatters.rst +++ b/docs/source/internal/formatters.rst @@ -30,7 +30,7 @@ The former allows us to inspect the value provided to ``--format`` by the user and alter our own format based on that value. The second simply uses that format string to format the error. -.. autoclass:: flake8.formatters.default.Default +.. autoclass:: flake8.formatting.default.Default :members: Pylint Formatter @@ -39,9 +39,9 @@ Pylint Formatter The |PylintFormatter| simply defines the default Pylint format string from pep8: ``'%(path)s:%(row)d: [%(code)s] %(text)s'``. -.. autoclass:: flake8.formatters.default.Pylint +.. autoclass:: flake8.formatting.default.Pylint :members: -.. |DefaultFormatter| replace:: :class:`~flake8.formatters.default.Default` -.. |PylintFormatter| replace:: :class:`~flake8.formatters.default.Pylint` +.. |DefaultFormatter| replace:: :class:`~flake8.formatting.default.Default` +.. |PylintFormatter| replace:: :class:`~flake8.formatting.default.Pylint` diff --git a/docs/source/internal/plugin_handling.rst b/docs/source/internal/plugin_handling.rst index e430bfb..b3b9b0e 100644 --- a/docs/source/internal/plugin_handling.rst +++ b/docs/source/internal/plugin_handling.rst @@ -98,8 +98,10 @@ API Documentation :members: .. autoclass:: flake8.plugins.manager.Checkers + :members: .. autoclass:: flake8.plugins.manager.Listeners + :members: build_notifier .. autoclass:: flake8.plugins.manager.ReportFormatters diff --git a/docs/source/internal/utils.rst b/docs/source/internal/utils.rst index 69dee45..d8adeac 100644 --- a/docs/source/internal/utils.rst +++ b/docs/source/internal/utils.rst @@ -45,3 +45,56 @@ strings that should be paths. This function retrieves and caches the value provided on ``sys.stdin``. This allows plugins to use this to retrieve ``stdin`` if necessary. + +.. autofunction:: flake8.utils.is_windows + +This provides a convenient and explicitly named function that checks if we are +currently running on a Windows (or ``nt``) operating system. + +.. autofunction:: flake8.utils.is_using_stdin + +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. + +.. autofunction:: flake8.utils.filenames_from + +When provided an argument to Flake8, we need to be able to traverse +directories in a convenient manner. For example, if someone runs + +.. code:: + + $ flake8 flake8/ + +Then they want us to check all of the files in the directory ``flake8/``. This +function will handle that while also handling the case where they specify a +file like: + +.. code:: + + $ flake8 flake8/__init__.py + + +.. autofunction:: flake8.utils.fnmatch + +The standard library's :func:`fnmatch.fnmatch` is excellent at deciding if a +filename matches a single pattern. In our use case, however, we typically have +a list of patterns and want to know if the filename matches any of them. This +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 +expecting. Plugins may expect one of the following: + +- ``physical_line`` to receive the line as it appears in the file + +- ``logical_line`` to receive the logical line (not as it appears in the file) + +- ``tree`` to receive the abstract syntax tree (AST) for the file + +We also analyze the rest of the parameters to provide more detail to the +plugin. This function will return the parameters in a consistent way across +versions of Python and will handle both classes and functions that are used as +plugins. Further, if the plugin is a class, it will strip the ``self`` +argument so we can check the parameters of the plugin consistently. diff --git a/flake8/utils.py b/flake8/utils.py index cd1cf72..7e08e41 100644 --- a/flake8/utils.py +++ b/flake8/utils.py @@ -106,7 +106,8 @@ def filenames_from(arg, predicate=None): :param callable predicate: Predicate to use to filter out filenames. If the predicate returns ``True`` we will exclude the filename, otherwise we - will yield it. + will yield it. By default, we include every filename + generated. :returns: Generator of paths """ diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py index 615f327..28b8e02 100644 --- a/tests/unit/test_utils.py +++ b/tests/unit/test_utils.py @@ -64,6 +64,12 @@ def test_fnmatch(filename, patterns, expected): assert utils.fnmatch(filename, patterns) is expected +def test_fnmatch_returns_the_default_with_empty_default(): + """The default parameter should be returned when no patterns are given.""" + sentinel = object() + assert utils.fnmatch('file.py', [], default=sentinel) is sentinel + + def test_filenames_from_a_directory(): """Verify that filenames_from walks a directory.""" filenames = list(utils.filenames_from('flake8/'))