pyre-ast
  1. Overview
  2. Docs

This module provides a type that represents a parameter list at each function definition site.

This structure is complicated because Python needs to distinguish among 5 kinds of parameters:

  • Regular parameters, which can be specified at callsites both positionally and as keyword arguments.
  • Positional-only parameters, which can only be specified at callsites positionally (see PEP 570).
  • Keyword-only parameters, which can only be specified at callsites as keyword arguments (see PEP 3102).
  • Special vararg parameter of the form *arg, representing the "rest" of both the positional-only and regular parameters.
  • Special kwarg parameter of the form **kwarg, representing the "rest" of both the regular and keyword-only parameters.

Parameter lists in Python can be generally chopped into three chunks: the positional-only chunk, followed by the regular chunk, followed by the keyword-only chunk. Positional-only chunk and regular chunk are separated by /, and regular chunk and keyword-only chunk are separated by *.

Example:

def foo(a, b=1, /, c=2, *, e, f=3, **g): ...

Here a and b are positional-only parameters. c is a regular parameter. e and f are keyword-only parameters. There is no special vararg parameter, and there is one special kwarg parameter g.

type ('arg, 'expr, 'arguments) t = posonlyargs:'arg list -> args:'arg list -> vararg:'arg option -> kwonlyargs:'arg list -> kw_defaults:'expr option list -> kwarg:'arg option -> defaults:'expr list -> 'arguments

Structure of this type mirrors the structure of the parameter list mentioned in the documentation of the containing module:

  • posonlyargs represents the list of positional-only parameters.
  • args represents the list of regular parameters.
  • kwonlyarg represents the list of keyword-only parameters.
  • vararg represents the special vararg parameter, if there is one.
  • kwarg represents the special kwarg parameter, if there is one.
  • defaults represents the list of default values for both positional-only and regular parameters. Note that in Python, regular parameters always comes after positional-only parameters. Also, if a parameter has a default value, then every positional-only/regular parameter that comes after it must have a default value as well. Hence there is no ambiguity regarding which default value in the defaults list corresponds to which parameter -- with the aforementioned rules there is only one possible interpretation.
  • kw_defaults represents the list of default values for keyword-only parameters. This list should always have the same length with kwonlyarg. If a keyword-only parameter does not have a default value, the corresponding element in kw_defaults will be unset.