API Reference

flake8_dunder_all

A Flake8 plugin and pre-commit hook which checks to ensure modules have defined __all__.

Classes:

AlphabeticalOptions(value)	Enum of possible values for the --dunder-all-alphabetical option.
Plugin(tree)	A Flake8 plugin which checks to ensure modules have defined __all__.
Visitor([use_endlineno])	AST NodeVisitor to check a module has defined __all__, and add one if it not.

Functions:

check_and_add_all(filename[, quote_type, …])

Check the given filename for the presence of a __all__ declaration, and add one if none is found.

class AlphabeticalOptions(value)

Bases: Enum

Enum of possible values for the --dunder-all-alphabetical option.

New in version 0.5.0.

class Plugin(tree)

Bases: object

A Flake8 plugin which checks to ensure modules have defined __all__.

Parameters

tree (AST) – The abstract syntax tree (AST) to check.

Methods:

run()

Run the plugin.

Attributes:

version

The plugin version

run()

Run the plugin.

Yields four-element tuples, consisting of:

1. The line number of the error.

2. The column offset of the error.

3. The error message.

4. The class of the plugin raising the error.

Return type

Generator[Tuple[int, int, str, Type[Any]], None, None]

version = '0.5.0'

Type:    str

The plugin version

class Visitor(use_endlineno=False)

Bases: NodeVisitor

AST NodeVisitor to check a module has defined __all__, and add one if it not.

Parameters

use_endlineno (bool) – Flag to indicate whether the end_lineno functionality is available. This functionality is available on Python 3.8 and above, or when the tree has been passed through flake8_dunder_all.utils.mark_text_ranges`(). Default False.

Changed in version 0.5.0: Added the sorted_upper_first, sorted_lower_first and all_lineno attributes.

Attributes:

all_lineno	The line number where __all__ is defined.
all_members	The value of __all__.
found_all	Flag to indicate a __all__ declaration has been found in the AST.
last_import	The lineno of the last top-level or conditional import
members	List of functions and classed defined in the AST

Methods:

generic_visit(node)	Called if no explicit visitor function exists for a node.
handle_def(node)	Handles def foo(): ..., async def foo(): ... and class Foo: ....
handle_import(node)	Handles import foo and from foo import bar.
visit(node)	Visit a node.
visit_AsyncFunctionDef(node)	Visit async def foo(): ....
visit_ClassDef(node)	Visit class Foo: ....
visit_FunctionDef(node)	Visit def foo(): ....
visit_If(node)	Visit an if statement and check if it’s for TYPE_CHECKING.
visit_Import(node)	Visit import foo.
visit_ImportFrom(node)	Visit from foo import bar.
visit_Try(node)	Visit a Try statement.

all_lineno

Type:    int

The line number where __all__ is defined.

all_members

Type:    Optional[Sequence[str]]

The value of __all__.

found_all

Type:    bool

Flag to indicate a __all__ declaration has been found in the AST.

generic_visit(node)

Called if no explicit visitor function exists for a node.

handle_def(node)

Handles def foo(): ..., async def foo(): ... and class Foo: ....

Parameters

node (Union[FunctionDef, AsyncFunctionDef, ClassDef]) – The node being visited.

handle_import(node)

Handles import foo and from foo import bar.

Parameters

node (Union[Import, ImportFrom]) – The node being visited

last_import

Type:    int

The lineno of the last top-level or conditional import

members

Type:    Set[str]

List of functions and classed defined in the AST

visit(node)

Visit a node.

visit_AsyncFunctionDef(node)

Visit async def foo(): ....

Parameters

node (AsyncFunctionDef) – The node being visited.

visit_ClassDef(node)

Visit class Foo: ....

Parameters

node (ClassDef) – The node being visited.

visit_FunctionDef(node)

Visit def foo(): ....

Parameters

node (FunctionDef) – The node being visited.

visit_If(node)

Visit an if statement and check if it’s for TYPE_CHECKING.

Parameters

node (If) – The node being visited.

visit_Import(node)

Visit import foo.

Parameters

node (Import) – The node being visited

visit_ImportFrom(node)

Visit from foo import bar.

Parameters

node (ImportFrom) – The node being visited

visit_Try(node)

Visit a Try statement.

Parameters

node (Try) – The node being visited.

check_and_add_all(filename, quote_type='"', use_tuple=False)

Check the given filename for the presence of a __all__ declaration, and add one if none is found.

Parameters

• filename (Union[str, Path, PathLike]) – The filename of the Python source file (.py) to check.

• quote_type (str) – The type of quote to use for strings. Default '"'.

• use_tuple (bool) – Whether to use tuples instead of lists for __all__. Default False.

Return type

int

Returns

• 0 if the file already contains a __all__ declaration, has no function or class definitions, or has a `` # noqa: DALL000 ` comment.

• 1 If __all__ is absent.

• 4 if an error was encountered when parsing the file.

Changed in version 0.2.0: Now returns 0 and doesn’t add __all__ if the file contains a noqa: DALL000 comment.

Changed in version 0.3.0: Added the use_tuple argument.

flake8_dunder_all.__main__

Command-line entry point for flake8-dunder-all.

flake8_dunder_all.utils

General utility functions.

Functions:

get_docstring_lineno(node)	Returns the linenumber of the start of the docstring for node.
mark_text_ranges(node, source)	Recursively add the end_lineno and end_col_offset attributes to each child of node which already has the attributes lineno and col_offset.
tidy_docstring(docstring)	Tidy up the docstring for use as help text.

get_docstring_lineno(node)

Returns the linenumber of the start of the docstring for node.

Parameters

node (Union[FunctionDef, ClassDef, Module])

Return type

Optional[int]

mark_text_ranges(node, source)

Recursively add the end_lineno and end_col_offset attributes to each child of node which already has the attributes lineno and col_offset.

Parameters

• node (AST) – An AST node created with ast.parse().

• source (str) – The corresponding source code for the node.

tidy_docstring(docstring)

Tidy up the docstring for use as help text.

Return type

str