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]'))

Parse a comma-separated list.

Parameters:

• value (str) – String to be parsed and normalized.

• regexp (Pattern[str]) – Compiled regular expression used to split the value when it is a string.

Returns:

List of values with whitespace stripped.

Return type:

List[str]

parse_comma_separated_list() takes either a string like

"E121,W123,F904"
"E121,\nW123,\nF804"
" E121,\n\tW123,\n\tF804 "
" E121\n\tW123 \n\tF804"

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='.')

Normalize a single-path.

Returns:

The normalized path.

Parameters:

• path (str) –

• parent (str) –

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='.')

Normalize a list of paths relative to a parent directory.

Returns:

The normalized paths.

Parameters:

• paths (Sequence[str]) –

• parent (str) –

Return type:

List[str]

This function utilizes normalize_path() to normalize a sequence of paths. See normalize_path() for what defines a normalized path.

flake8.utils.stdin_get_value()

Get and cache it so plugins can use it.

Return type:

str

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_using_stdin(paths)

Determine if we’re going to read from stdin.

Parameters:

paths (List[str]) – 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.fnmatch(filename, patterns)

Wrap fnmatch.fnmatch() to add some functionality.

Parameters:

• filename (str) – Name of the file we’re trying to match.

• patterns (Sequence[str]) – Patterns we’re using to try to match the filename.

• default – The default value if patterns is empty

Returns:

True if a pattern matches the filename, False if it doesn’t. True if patterns is empty.

Return type:

bool

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.parse_unified_diff(diff=None)

Parse the unified diff passed on stdin.

Returns:

dictionary mapping file names to sets of line numbers

Parameters:

diff (str | None) –

Return type:

Dict[str, Set[int]]

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.