Visitors

Contains detailed technical documentation about how to write a visitor.

See also

Visitor is a well-known software engineering pattern: https://en.wikipedia.org/wiki/Visitor_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.

Conventions

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.

Reference

class BaseVisitor(options, filename='stdin')

Bases: object

Abstract base class for different types of visitors.

options

contains the options objects passed and parsed by flake8.

filename

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

violations

list of violations for the specific visitor.

classmethod from_checker(checker)

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

add_violation(violation)

Adds violation to the visitor.

Return type:None

run()

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)

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.

tree

ast tree to be checked.

classmethod from_checker(checker)

Constructs visitor instance from the checker.

Return type:BaseNodeVisitor

run()

Recursively visits all ast nodes. Then executes post hook.

Return type:None

class BaseFilenameVisitor(options, filename='stdin')

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.

stem

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

visit_filename()

Abstract method to check module file names.

This method should be overridden in a subclass.

Return type:None

run()

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)

Bases: wemake_python_styleguide.visitors.base.BaseVisitor

Allows to check tokenize sequences.

file_tokens

tokenize.TokenInfo sequence to be checked.

classmethod from_checker(checker)

Constructs tokenize based visitor instance from the checker.

Return type:BaseTokenVisitor

visit(token)

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.

See also

https://docs.python.org/3/library/tokenize.html

Return type:None

run()

Visits all token types that have a handler method.

Return type:None