# eric7.Plugins.CheckerPlugins.CodeStyleChecker.Annotations.AnnotationsFunctionVisitor

Module implementing a node visitor for function type annotations.

### Global Attributes

AST_ARG_TYPES

### Classes

Argument | Class representing a function argument.
Function | Class representing a function.
FunctionVisitor | Class implementing a node visitor to check function annotations.
ReturnVisitor | Class implementing a node visitor to check the return statements of a function node.

### Functions

None

## Argument

Class representing a function argument.

### Derived from

None

### Class Attributes

None

### Class Methods

fromNode | Class method to create an Argument object based on the given node.

### Methods

Argument | Constructor

### Static Methods

None

#### Argument.fromNode (class method)

fromNode(node, annotationTypeName)

Class method to create an Argument object based on the given node.

node (ast.arguments)
  reference to the node to be converted
annotationTypeName (str)
  name of the annotation type

Return:
  Argument object

Return Type:
  Argument

#### Argument (Constructor)

Argument(argname, lineno, col_offset, annotationType, hasTypeAnnotation=False, has3107Annotation=False, hasTypeComment=False, )

Constructor

argname (str)
  name of the argument
lineno (int)
  line number
col_offset (int)
  column number
annotationType (AnnotationType)
  type of annotation
hasTypeAnnotation (bool (optional))
  flag indicating the presence of a type annotation (defaults to False)
has3107Annotation (bool (optional))
  flag indicating the presence of a PEP 3107 annotation (defaults to False)
hasTypeComment (bool (optional))
  flag indicating the presence of a type comment (defaults to False)

Up

## Function

Class representing a function.

### Derived from

None

### Class Attributes

None

### Class Methods

fromNode | Class method to create a Function object from ast.FunctionDef or ast.AsyncFunctionDef nodes.

### Methods

Function | Constructor
__decoratorChecker | Private method to check the provided decorator for a match against the provided set of check names.
getAnnotatedArguments | Public method to get list of arguments with type annotations.
getMissedAnnotations | Public method to provide a list of arguments with missing type annotations.
hasDecorator | Public method to check whether the function node is decorated by any of the provided decorators.
isDynamicallyTyped | Public method to check, if a function definition is dynamically typed (i.e.
isFullyAnnotated | Public method to check, if the function definition is fully type annotated.

### Static Methods

_maybeInjectClassArgument | Static method to inject `self` or `cls` args into a type comment to align with PEP 3107-style annotations.
_singleLineColonSeeker | Static method to find the line & column indices of a single line function definition.
colonSeeker | Static method to find the line & column indices of the function definition's closing colon.
getClassDecoratorType | Static method to get the class method's decorator type from its function node.
getFunctionType | Static method to determine the function's FunctionType from its name.
tryTypeComment | Static method to infer type hints from a function-level type comment.

#### Function.fromNode (class method)

fromNode(node, lines, **kwargs)

Class method to create a Function object from ast.FunctionDef or ast.AsyncFunctionDef nodes.

Accept the source code, as a list of strings, in order to get the column where the function definition ends.

With exceptions, input kwargs are passed straight through to Function's __init__. The following kwargs will be overridden: * function_type * class_decorator_type * args

node (ast.AsyncFunctionDef or ast.FunctionDef)
  reference to the function definition node
lines (list of str)
  list of source code lines
**kwargs= (dict)
  keyword arguments

Return:
  created Function object

Return Type:
  Function

#### Function (Constructor)

Function(name, lineno, col_offset, functionType=FunctionType.PUBLIC, isClassMethod=False, classDecoratorType=None, isReturnAnnotated=False, hasTypeComment=False, hasOnlyNoneReturns=True, isNested=False, decoratorList=None, args=None, )

Constructor

name (str)
  name of the function
lineno (int)
  line number
col_offset (int)
  column number
functionType (FunctionType (optional))
  type of the function (defaults to FunctionType.PUBLIC)
isClassMethod (bool (optional))
  flag indicating a class method (defaults to False)
classDecoratorType (ClassDecoratorType or None (optional))
  type of a function decorator (defaults to None)
isReturnAnnotated (bool (optional))
  flag indicating the presence of a return type annotation (defaults to False)
hasTypeComment (bool (optional))
  flag indicating the presence of a type comment (defaults to False)
hasOnlyNoneReturns (bool (optional))
  flag indicating only None return values (defaults to True)
isNested (bool (optional))
  flag indicating a nested function (defaults to False)
decoratorList (list of ast.Attribute, ast.Call or ast.Name (optional))
  list of decorator nodes (defaults to None)
args (list of Argument (optional))
  list of arguments (defaults to None)

#### Function.__decoratorChecker

__decoratorChecker(decorator, checkDecorators)

Private method to check the provided decorator for a match against the provided set of check names.

Decorators are assumed to be of the following form: * `a.name` or `a.name()` * `name` or `name()`

Note: Deeper imports (e.g. `a.b.name`) are not explicitly supported.

decorator (ast.Attribute, ast.Call or ast.Name)
  decorator node to check
checkDecorators (set of str)
  set of decorators to check against

Return:
  flag indicating the presence of any decorators

Return Type:
  bool

#### Function.getAnnotatedArguments

getAnnotatedArguments()

Public method to get list of arguments with type annotations.

Return:
  list of arguments with type annotations.

Return Type:
  list of Argument

#### Function.getMissedAnnotations

getMissedAnnotations()

Public method to provide a list of arguments with missing type annotations.

Return:
  list of arguments with missing type annotations

Return Type:
  list of Argument

#### Function.hasDecorator

hasDecorator(checkDecorators)

Public method to check whether the function node is decorated by any of the provided decorators.

Decorator matching is done against the provided `checkDecorators` set. Decorators are assumed to be either a module attribute (e.g. `@typing.overload`) or name (e.g. `@overload`). For the case of a module attribute, only the attribute is checked against `overload_decorators`.

Note: Deeper decorator imports (e.g. `a.b.overload`) are not explicitly supported.

checkDecorators (set of str)
  set of decorators to check against

Return:
  flag indicating the presence of any decorators

Return Type:
  bool

#### Function.isDynamicallyTyped

isDynamicallyTyped()

Public method to check, if a function definition is dynamically typed (i.e. completely lacking hints).

Return:
  flag indicating a dynamically typed function definition

Return Type:
  bool

#### Function.isFullyAnnotated

isFullyAnnotated()

Public method to check, if the function definition is fully type annotated.

Note: self.args will always include an Argument object for return.

Return:
  flag indicating a fully annotated function definition

Return Type:
  bool

#### Function._maybeInjectClassArgument (static)

_maybeInjectClassArgument(funcObj)

Static method to inject `self` or `cls` args into a type comment to align with PEP 3107-style annotations.

Because PEP 484 does not describe a method to provide partial function- level type comments, there is a potential for ambiguity in the context of both class methods and classmethods when aligning type comments to method arguments.

These two class methods, for example, should lint equivalently:

def bar(self, a): # type: (int) -> int ...

def bar(self, a: int) -> int ...

When this example type comment is parsed by `ast` and then matched with the method's arguments, it associates the `int` hint to `self` rather than `a`, so a dummy hint needs to be provided in situations where `self` or `class` are not hinted in the type comment in order to achieve equivalent linting results to PEP-3107 style annotations.

A dummy `ast.Ellipses` constant is injected if the following criteria are met: 1. The function node is either a class method or classmethod 2. The number of hinted args is at least 1 less than the number of function args

hintTree (ast.FunctionType)
  parsed type hint node
funcObj (Function)
  reference to the Function object

Return:
  reference to the hint node

Return Type:
  ast.FunctionType

#### Function._singleLineColonSeeker (static)

_singleLineColonSeeker(line)

Static method to find the line & column indices of a single line function definition.

node (ast.AsyncFunctionDef or ast.FunctionDef)
  reference to the function definition node
line (str)
  source code line

Return:
  line and column offset of the colon

Return Type:
  tuple of (int, int)

#### Function.colonSeeker (static)

colonSeeker(lines)

Static method to find the line & column indices of the function definition's closing colon.

node (ast.AsyncFunctionDef or ast.FunctionDef)
  reference to the function definition node
lines (list of str)
  list of source code lines

Return:
  line and column offset of the colon

Return Type:
  tuple of (int, int)

#### Function.getClassDecoratorType (static)

getClassDecoratorType()

Static method to get the class method's decorator type from its function node.

Only @classmethod and @staticmethod decorators are identified; all other decorators are ignored

If @classmethod or @staticmethod decorators are not present, this function will return None.

functionNode (ast.AsyncFunctionDef or ast.FunctionDef)
  reference to the function definition node

Return:
  class decorator type

Return Type:
  ClassDecoratorType or None

#### Function.getFunctionType (static)

getFunctionType()

Static method to determine the function's FunctionType from its name.

MethodType is determined by the following priority: 1. Special: function name prefixed & suffixed by "__" 2. Private: function name prefixed by "__" 3. Protected: function name prefixed by "_" 4. Public: everything else

functionName (str)
  function name to be checked

Return:
  type of function

Return Type:
  FunctionType

#### Function.tryTypeComment (static)

tryTypeComment(node)

Static method to infer type hints from a function-level type comment.

If a function is type commented it is assumed to have a return annotation, otherwise Python will fail to parse the hint.

funcObj (Function)
  reference to the Function object
node (ast.AsyncFunctionDef or ast.FunctionDef)
  reference to the function definition node

Return:
  reference to the modified Function object

Return Type:
  Function

Up

## FunctionVisitor

Class implementing a node visitor to check function annotations.

### Derived from

ast.NodeVisitor

### Class Attributes

AstFuncTypes
visit_AsyncFunctionDef
visit_ClassDef
visit_FunctionDef

### Class Methods

None

### Methods

FunctionVisitor | Constructor
switchContext | Public method implementing a context switcher as a generic function visitor in order to track function context.

### Static Methods

None

#### FunctionVisitor (Constructor)

FunctionVisitor(lines)

Constructor

lines (list of str)
  source code lines of the function

#### FunctionVisitor.switchContext

switchContext(node)

Public method implementing a context switcher as a generic function visitor in order to track function context.

Without keeping track of context, it's challenging to reliably differentiate class methods from "regular" functions, especially in the case of nested classes.

node (ast.AsyncFunctionDef or ast.FunctionDef)
  reference to the function definition node to be analyzed

Up

## ReturnVisitor

Class implementing a node visitor to check the return statements of a function node.

If the function node being visited has an explicit return statement of anything other than `None`, the `instance.hasOnlyNoneReturns` flag will be set to `False`.

If the function node being visited has no return statement, or contains only return statement(s) that explicitly return `None`, the `instance.hasOnlyNoneReturns` flag will be set to `True`.

Due to the generic visiting being done, we need to keep track of the context in which a non-`None` return node is found. These functions are added to a set that is checked to see whether nor not the parent node is present.

### Derived from

ast.NodeVisitor

### Class Attributes

visit_AsyncFunctionDef
visit_FunctionDef

### Class Methods

None

### Methods

ReturnVisitor | Constructor
hasOnlyNoneReturns | Public method indicating, that the parent node isn't in the visited nodes that don't return `None`.
switchContext | Public method implementing a context switcher as a generic function visitor in order to track function context.
visit_Return | Public method to check each Return node to see if it returns anything other than `None`.

### Static Methods

None

#### ReturnVisitor (Constructor)

ReturnVisitor(parentNode)

Constructor

parentNode (ast.AsyncFunctionDef or ast.FunctionDef)
  reference to the function definition node to be analyzed

#### ReturnVisitor.hasOnlyNoneReturns

hasOnlyNoneReturns()

Public method indicating, that the parent node isn't in the visited nodes that don't return `None`.

Return:
  flag indicating, that the parent node isn't in the visited nodes that don't return `None`

Return Type:
  bool

#### ReturnVisitor.switchContext

switchContext(node)

Public method implementing a context switcher as a generic function visitor in order to track function context.

Without keeping track of context, it's challenging to reliably differentiate class methods from "regular" functions, especially in the case of nested classes.

node (ast.AsyncFunctionDef or ast.FunctionDef)
  reference to the function definition node to be analyzed

#### ReturnVisitor.visit_Return

visit_Return(node)

Public method to check each Return node to see if it returns anything other than `None`.

If the node being visited returns anything other than `None`, its parent context is added to the set of non-returning child nodes of the parent node.

node (ast.Return)
  reference to the AST Return node

Up