API Reference

flake8_dunder_all

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

Classes:

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 Plugin(tree)[source]

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()[source]

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.4.0'

Type:    str

The plugin version

class Visitor(use_endlineno=False)[source]

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.

Attributes:

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_Name(node)

Visit a variable.

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)[source]

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

Parameters

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

handle_import(node)[source]

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)[source]

Visit async def foo(): ....

Parameters

node (AsyncFunctionDef) – The node being visited.

visit_ClassDef(node)[source]

Visit class Foo: ....

Parameters

node (ClassDef) – The node being visited.

visit_FunctionDef(node)[source]

Visit def foo(): ....

Parameters

node (FunctionDef) – The node being visited.

visit_If(node)[source]

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

Parameters

node (If) – The node being visited.

visit_Import(node)[source]

Visit import foo.

Parameters

node (Import) – The node being visited

visit_ImportFrom(node)[source]

Visit from foo import bar.

Parameters

node (ImportFrom) – The node being visited

visit_Name(node)[source]

Visit a variable.

Parameters

node (Name) – The node being visited.

check_and_add_all(filename, quote_type='"', use_tuple=False)[source]

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)[source]

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)[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)[source]

Tidy up the docstring for use as help text.

Return type

str