Utility Functions¶
Flake8 has a few utility functions that it uses internally.
Warning
As should be implied by where these are documented, these are all internal utility functions. Their signatures and return types may change between releases without notice.
Bugs reported about these internal functions will be closed immediately.
If functions are needed by plugin developers, they may be requested in the bug tracker and after careful consideration they may be added to the documented stable API.
-
flake8.utils.
parse_comma_separated_list
(value, regexp=re.compile('[,\\s]'))[source]¶ Parse a comma-separated list.
Parameters: - value – String or list of strings to be parsed and normalized.
- regexp (_sre.SRE_Pattern) – Compiled regular expression used to split the value when it is a string.
Returns: List of values with whitespace stripped.
Return type:
parse_comma_separated_list()
takes either a string like
"E121,W123,F904"
"E121,\nW123,\nF804"
"E121,\n\tW123,\n\tF804"
Or it will take a list of strings (potentially with whitespace) such as
[" E121\n", "\t\nW123 ", "\n\tF904\n "]
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
additional parameters to Option
.
-
flake8.utils.
normalize_path
(path, parent='.')[source]¶ Normalize a single-path.
Returns: The normalized path. Return type: str
This utility takes a string that represents a path and returns the absolute
path if the string has a /
in it. It also removes trailing /
s.
-
flake8.utils.
normalize_paths
(paths, parent='.')[source]¶ Parse a comma-separated list of paths.
Returns: The normalized paths. Return type: [str]
This function utilizes parse_comma_separated_list()
and
normalize_path()
to normalize its input to a list of
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.
-
flake8.utils.
is_windows
()[source]¶ Determine if we’re running on Windows.
Returns: True if running on Windows, otherwise False Return type: bool
This provides a convenient and explicitly named function that checks if we are
currently running on a Windows (or nt
) operating system.
-
flake8.utils.
can_run_multiprocessing_on_windows
()[source]¶ Determine if we can use multiprocessing on Windows.
This presently will always return False due to a bug in the
multiprocessing
module on Windows. Once fixed, we will check to ensure that the version of Python contains that fix (via version inspection) and conditionally re-enable support on Windows.Returns: True if the version of Python is modern enough, otherwise False Return type: bool
This provides a separate and distinct check from
is_windows()
that allows us to check if the version of
Python we’re using can actually use multiprocessing on Windows.
-
flake8.utils.
is_using_stdin
(paths)[source]¶ Determine if we’re going to read from stdin.
Parameters: paths (list) – The paths that we’re going to check. Returns: True if stdin (-) is in the path, otherwise False Return type: bool
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.utils.
filenames_from
(arg, predicate=None)[source]¶ Generate filenames from an argument.
Parameters: - arg (str) – Parameter from the command-line.
- predicate (callable) – Predicate to use to filter out filenames. If the predicate
returns
True
we will exclude the filename, otherwise we will yield it. By default, we include every filename generated.
Returns: Generator of paths
When provided an argument to Flake8, we need to be able to traverse directories in a convenient manner. For example, if someone runs
$ 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:
$ flake8 flake8/__init__.py
-
flake8.utils.
fnmatch
(filename, patterns, default=True)[source]¶ Wrap
fnmatch.fnmatch()
to add some functionality.Parameters: Returns: True if a pattern matches the filename, False if it doesn’t.
default
if patterns is empty.
The standard library’s 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.
-
flake8.utils.
parameters_for
(plugin)[source]¶ Return the parameters for the plugin.
This will inspect the plugin and return either the function parameters if the plugin is a function or the parameters for
__init__
afterself
if the plugin is a class.Parameters: plugin (flake8.plugins.manager.Plugin) – The internal plugin object. Returns: A dictionary mapping the parameter name to whether or not it is required (a.k.a., is positional only/does not have a default). Return type: dict([(str, bool)])
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 filelogical_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.
-
flake8.utils.
parse_unified_diff
(diff=None)[source]¶ Parse the unified diff passed on stdin.
Returns: dictionary mapping file names to sets of line numbers Return type: dict
To handle usage of 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
filenames as the keys and sets of line numbers as the value.