Contains detailed technical documentation about how to write a visitor.

See also

Visitor is a well-known software engineering pattern:

Each visitor might work with one or many violations. Multiple visitors might one with the same violation.

graph TD V1[Visitor 1] --> EA[Violation A] V1[Visitor 1] --> EB[Violation B] V2[Visitor 2] --> EA[Violation A] V2[Visitor 2] --> EC[Violation C] V3[Visitor 3] --> EZ[Violation Z]

Visitor relation with violations.

Visitors API

graph TD; BaseNodeVisitor BaseFilenameVisitor BaseVisitor BaseTokenVisitor NodeVisitor --> BaseNodeVisitor BaseVisitor --> BaseNodeVisitor BaseVisitor --> BaseFilenameVisitor BaseVisitor --> BaseTokenVisitor
BaseNodeVisitor Allows to store violations while traversing node tree.
BaseFilenameVisitor Abstract base class that allows to visit and check module file names.
BaseTokenVisitor Allows to check tokenize sequences.

The decision relies on what parameters do you need for the task. It is highly unlikely that you will need two parameters at the same time. See Tutorial for more information about choosing a correct base class.


Then you will have to write logic for your visitor. We follow these conventions:

  • Public visitor methods start with visit_, than comes the name of a token or node to be visited
  • All other methods and attributes should be protected
  • We try to separate as much logic from visit_ methods as possible, so they only route for callbacks that actually executes the checks
  • We place repeating logics into logics/ package to be able to reuse it

There are different example of visitors in this project already.


class BaseVisitor(options, filename='stdin')[source]

Bases: object

Abstract base class for different types of visitors.


contains the options objects passed and parsed by flake8.


filename passed by flake8, each visitor has a file name.


list of violations for the specific visitor.

classmethod from_checker(checker)[source]

Constructs visitor instance from the checker.

Each unique visitor class should know how to construct itself from the checker instance.

Generally speaking, each visitor class needs to eject required parameters from checker and then run its constructor with these parameters.

Return type:BaseVisitor

Adds violation to the visitor.

Return type:None

Abstract method to run a visitor.

Each visitor should know what exactly it needs to do when it was told to run. This method should be defined in all subclasses.

Return type:None
class BaseNodeVisitor(options, tree, **kwargs)[source]

Bases: ast.NodeVisitor, wemake_python_styleguide.visitors.base.BaseVisitor

Allows to store violations while traversing node tree.

This class should be used as a base class for all ast based checkers. Method visit() is defined in NodeVisitor class.


ast tree to be checked.

classmethod from_checker(checker)[source]

Constructs visitor instance from the checker.

Return type:BaseNodeVisitor

Recursively visits all ast nodes. Then executes post hook.

Return type:None
class BaseFilenameVisitor(options, filename='stdin')[source]

Bases: wemake_python_styleguide.visitors.base.BaseVisitor

Abstract base class that allows to visit and check module file names.

Has visit_filename() method that should be defined in subclasses.


the last part of the filename. Does not contain extension.


Abstract method to check module file names.

This method should be overridden in a subclass.

Return type:None

Checks module’s filename.

Skips modules that are checked as piped output. Since these modules are checked as a stdin input. And do not have names.

Return type:None
class BaseTokenVisitor(options, file_tokens, **kwargs)[source]

Bases: wemake_python_styleguide.visitors.base.BaseVisitor

Allows to check tokenize sequences.


tokenize.TokenInfo sequence to be checked.

classmethod from_checker(checker)[source]

Constructs tokenize based visitor instance from the checker.

Return type:BaseTokenVisitor

Runs custom defined handlers in a visitor for each specific token type.

Uses .exact_type property to fetch the token name. So, you have to be extra careful with tokens like -> and other operators, since they might resolve in just OP name.

Does nothing if handler for any token type is not defined.

Inspired by NodeVisitor class.

Return type:None

Visits all token types that have a handler method.

Return type:None