Nodes

CSTNode and its subclasses cover Python’s full grammar in a whitespace-sensitive fashion, forming LibCST’s concrete syntax tree.

Many of these nodes are designed to behave similarly to Python’s abstract syntax tree.

CSTNode

The base node type which all other nodes derive from.

class libcst.CSTNode[source]

validate_types_shallow() → None[source]

Compares the type annotations on a node’s fields with those field’s actual values at runtime. Raises a TypeError is a mismatch is found.

Only validates the current node, not any of it’s children. For a recursive version, see validate_types_deep().

If you’re using a static type checker (highly recommended), this is useless. However, if your code doesn’t use a static type checker, or if you’re unable to statically type your code for some reason, you can use this method to help validate your tree.

Some (non-typing) validation is done unconditionally during the construction of a node. That validation does not overlap with the work that validate_types_deep() does.

validate_types_deep() → None[source]: Like validate_types_shallow(), but recursively validates the whole tree.

property children: Sequence[libcst._nodes.base.CSTNode]

The immediate (not transitive) child CSTNodes of the current node. Various properties on the nodes, such as string values, will not be visited if they are not a subclass of CSTNode.

Iterable properties of the node (e.g. an IndentedBlock’s body) will be flattened into the children’s sequence.

The children will always be returned in the same order that they appear lexically in the code.

visit(visitor: Union[libcst._visitors.CSTTransformer, libcst._visitors.CSTVisitor]) → Union[libcst._nodes.base._CSTNodeSelfT, libcst._removal_sentinel.RemovalSentinel, libcst._flatten_sentinel.FlattenSentinel[libcst._nodes.base._CSTNodeSelfT]][source]: Visits the current node, its children, and all transitive children using the given visitor’s callbacks.

with_changes(**changes: Any) → libcst._nodes.base._CSTNodeSelfT[source]

A convenience method for performing mutation-like operations on immutable nodes. Creates a new object of the same type, replacing fields with values from the supplied keyword arguments.

For example, to update the test of an if conditional, you could do:

def leave_If(self, original_node: cst.If, updated_node: cst.If) -> cst.If:
    new_node = updated_node.with_changes(test=new_conditional)
    return new_node

new_node will have the same body, orelse, and whitespace fields as updated_node, but with the updated test field.

The accepted arguments match the arguments given to __init__, however there are no required or positional arguments.

TODO: This API is untyped. There’s probably no sane way to type it using pyre’s current feature-set, but we should still think about ways to type this or a similar API in the future.

deep_clone() → libcst._nodes.base._CSTNodeSelfT[source]

Recursively clone the entire tree. The created tree is a new tree has the same representation but different identity.

>>> tree = cst.parse_expression("1+2")

>>> tree.deep_clone() == tree
False

>>> tree == tree
True

>>> tree.deep_equals(tree.deep_clone())
True

deep_equals(other: libcst._nodes.base.CSTNode) → bool[source]: Recursively inspects the entire tree under self and other to determine if the two trees are equal by representation instead of identity (==).

deep_replace(old_node: libcst._nodes.base.CSTNode, new_node: libcst._types.CSTNodeT) → Union[libcst._nodes.base._CSTNodeSelfT, libcst._types.CSTNodeT][source]: Recursively replaces any instance of old_node with new_node by identity. Use this to avoid nested with_changes blocks when you are replacing one of a node’s deep children with a new node. Note that if you have previously modified the tree in a way that old_node appears more than once as a deep child, all instances will be replaced.

deep_remove(old_node: libcst._nodes.base.CSTNode) → Union[libcst._nodes.base._CSTNodeSelfT, libcst._removal_sentinel.RemovalSentinel][source]: Recursively removes any instance of old_node by identity. Note that if you have previously modified the tree in a way that old_node appears more than once as a deep child, all instances will be removed.

with_deep_changes(old_node: libcst._nodes.base.CSTNode, **changes: Any) → libcst._nodes.base._CSTNodeSelfT[source]

A convenience method for applying with_changes to a child node. Use this to avoid chains of with_changes or combinations of deep_replace and with_changes.

The accepted arguments match the arguments given to the child node’s __init__.

TODO: This API is untyped. There’s probably no sane way to type it using pyre’s current feature-set, but we should still think about ways to type this or a similar API in the future.

classmethod field(*args: object, **kwargs: object) → Any[source]: A helper that allows us to easily use CSTNodes in dataclass constructor defaults without accidentally aliasing nodes by identity across multiple instances.

Module

A node that represents an entire python module.

class libcst.Module[source]

Contains some top-level information inferred from the file letting us set correct defaults when printing the tree about global formatting rules. All code parsed with parse_module() will be encapsulated in a module.

body: A list of zero or more statements that make up this module.

header: Normally any whitespace/comments are assigned to the next node visited, but Module is a special case, and comments at the top of the file tend to refer to the module itself, so we assign them to the Module instead of the first statement in the body.

footer: Any trailing whitespace/comments found after the last statement.

encoding

The file’s encoding format. When parsing a bytes object, this value may be inferred from the contents of the parsed source code. When parsing a str, this value defaults to "utf-8".

This value affects how bytes encodes the source code.

default_indent: The indentation of the file, expressed as a series of tabs and/or spaces. This value is inferred from the contents of the parsed source code by default.

default_newline: The newline of the file, expressed as \n, \r\n, or \r. This value is inferred from the contents of the parsed source code by default.

has_trailing_newline: Whether the module has a trailing newline or not.

visit(visitor: Union[CSTTransformer, CSTVisitor]) → libcst._nodes.module._ModuleSelfT[source]

Returns the result of running a visitor over this module.

Module overrides the default visitor entry point to resolve metadata dependencies declared by ‘visitor’.

property code: str: The string representation of this module, respecting the inferred indentation and newline type.

property bytes: bytes: The bytes representation of this module, respecting the inferred indentation and newline type, using the current encoding.

code_for_node(node: libcst._nodes.base.CSTNode) → str[source]: Generates the code for the given node in the context of this module. This is a method of Module, not CSTNode, because we need to know the module’s default indentation and newline formats.

property config_for_parsing: PartialParserConfig

Generates a parser config appropriate for passing to a parse_expression() or parse_statement() call. This is useful when using either parser function to generate code from a string template. By using a generated parser config instead of the default, you can guarantee that trees generated from both statement and expression strings have the same inferred defaults for things like newlines, indents and similar:

module = cst.parse_module("pass\n")
expression = cst.parse_expression("1 + 2", config=module.config_for_parsing)

get_docstring(clean: bool = True) → Optional[str][source]: Returns a inspect.cleandoc() cleaned docstring if the docstring is available, None otherwise.

Expressions

An expression is anything that represents a value (e.g. it could be returned from a function). All expressions subclass from BaseExpression.

Expression can be parsed with parse_expression() or as part of a statement or module using parse_statement() or parse_module().

class libcst.BaseExpression[source]: An base class for all expressions. BaseExpression contains no fields.

Names and Object Attributes

class libcst.Name[source]

A simple variable name. Names are typically used in the context of a variable access, an assignment, or a deletion.

Dotted variable names (a.b.c) are represented with Attribute nodes, and subscripted variable names (a[b]) are represented with Subscript nodes.

value: The variable’s name (or “identifier”) as a string.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.Attribute[source]

An attribute reference, such as x.y.

Note that in the case of x.y.z, the outer attribute will have an attr of z and the value will be another Attribute referencing the y attribute on x:

Attribute(
    value=Attribute(
        value=Name("x")
        attr=Name("y")
    ),
    attr=Name("z"),
)

value: An expression which, when evaluated, will produce an object with attr as an attribute.

attr: The name of the attribute being accessed on the value object.

dot: A separating dot. If there’s whitespace between the value and attr, this dot owns it.

lpar

rpar: Sequence of parenthesis for precedence dictation.

Operations and Comparisons

Operation and Comparison nodes combine one or more expressions with an operator.

class libcst.UnaryOperation[source]

Any generic unary expression, such as not x or -x. UnaryOperation nodes apply a BaseUnaryOp to an expression.

operator: The unary operator that applies some operation (e.g. negation) to the expression.

expression: The expression that should be transformed (e.g. negated) by the operator to create a new value.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.BinaryOperation[source]

An operation that combines two expression such as x << y or y + z. BinaryOperation nodes apply a BaseBinaryOp to an expression.

Binary operations do not include operations performed with BaseBooleanOp nodes, such as and or or. Instead, those operations are provided by BooleanOperation.

It also does not include support for comparision operators performed with BaseCompOp, such as <, >=, ==, is, or in. Instead, those operations are provided by Comparison.

left: The left hand side of the operation.

operator: The actual operator such as << or + that combines the left and right expressions.

right: The right hand side of the operation.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.BooleanOperation[source]

An operation that combines two booleans such as x or y or z and w BooleanOperation nodes apply a BaseBooleanOp to an expression.

Boolean operations do not include operations performed with BaseBinaryOp nodes, such as + or <<. Instead, those operations are provided by BinaryOperation.

It also does not include support for comparision operators performed with BaseCompOp, such as <, >=, ==, is, or in. Instead, those operations are provided by Comparison.

left: The left hand side of the operation.

operator: The actual operator such as and or or that combines the left and right expressions.

right: The right hand side of the operation.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.Comparison[source]

A comparison between multiple values such as x < y, x < y < z, or x in [y, z]. These comparisions typically result in boolean values.

Unlike BinaryOperation and BooleanOperation, comparisons are not restricted to a left and right child. Instead they can contain an arbitrary number of ComparisonTarget children.

x < y < z is not equivalent to (x < y) < z or x < (y < z). Instead, it’s roughly equivalent to x < y and y < z.

For more details, see Python’s documentation on comparisons.

# x < y < z

Comparison(
    Name("x"),
    [
        ComparisonTarget(LessThan(), Name("y")),
        ComparisonTarget(LessThan(), Name("z")),
    ],
)

left: The first value in the full sequence of values to compare. This value will be compared against the first value in comparisions.

comparisons: Pairs of BaseCompOp operators and expression values to compare. These come after left. Each value is compared against the value before and after itself in the sequence.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.ComparisonTarget[source]

A target for a Comparison. Owns the comparison operator and the value to the right of the operator.

operator: A comparison operator such as <, >=, ==, is, or in.

comparator: The right hand side of the comparison operation.

Control Flow

class libcst.Asynchronous[source]

Used by asynchronous function definitions, as well as async for and async with.

whitespace_after: Any space that appears directly after this async keyword.

class libcst.Await[source]

An await expression. Await expressions are only valid inside the body of an asynchronous FunctionDef or (as of Python 3.7) inside of an asynchronous GeneratorExp nodes.

expression: The actual expression we need to wait for.

lpar

rpar: Sequence of parenthesis for precedence dictation.

whitespace_after_await: Whitespace that appears after the async keyword, but before the inner expression.

class libcst.Yield[source]

A yield expression similar to yield x or yield from fun().

To learn more about the ways that yield can be used in generators, refer to Python’s language reference.

value: The value yielded from the generator, in the case of a From clause, a sub-generator to iterate over.

lpar

rpar: Sequence of parenthesis for precedence dictation.

whitespace_after_yield: Whitespace after the yield keyword, but before the value.

class libcst.From[source]

A from x stanza in a Yield or Raise.

item: The expression that we are yielding/raising from.

whitespace_before_from: The whitespace at the very start of this node.

whitespace_after_from: The whitespace after the from keyword, but before the item.

class libcst.IfExp[source]

An if expression of the form body if test else orelse.

If statements are provided by If and Else nodes.

test: The test to perform.

body: The expression to evaluate when the test is true.

orelse: The expression to evaluate when the test is false.

lpar

rpar: Sequence of parenthesis for precedence dictation.

whitespace_before_if: Whitespace after the body expression, but before the if keyword.

whitespace_after_if: Whitespace after the if keyword, but before the test clause.

whitespace_before_else: Whitespace after the test expression, but before the else keyword.

whitespace_after_else: Whitespace after the else keyword, but before the orelse expression.

Lambdas and Function Calls

class libcst.Lambda[source]

A lambda expression that creates an anonymous function.

Lambda(
    params=Parameters([Param(Name("arg"))]),
    body=Ellipsis(),
)

Represents the following code:

lambda arg: ...

Named functions statements are provided by FunctionDef.

params: The arguments to the lambda. This is similar to the arguments on a FunctionDef, however lambda arguments are not allowed to have an Annotation.

body: The value that the lambda computes and returns when called.

colon: The colon separating the parameters from the body.

lpar

rpar: Sequence of parenthesis for precedence dictation.

whitespace_after_lambda: Whitespace after the lambda keyword, but before any argument or the colon.

class libcst.Call[source]

An expression representing a function call, such as do_math(1, 2) or picture.post_on_instagram().

Function calls consist of a function name and a sequence of arguments wrapped in Arg nodes.

func: The expression resulting in a callable that we are to call. Often a Name or Attribute.

args: The arguments to pass to the resulting callable. These may be a mix of positional arguments, keyword arguments, or “starred” arguments.

lpar

rpar: Sequence of parenthesis for precedence dictation. These are not the parenthesis before and after the list of args, but rather arguments around the entire call expression, such as (( do_math(1, 2) )).

whitespace_after_func: Whitespace after the func name, but before the opening parenthesis.

whitespace_before_args: Whitespace after the opening parenthesis but before the first argument (if there are any). Whitespace after the last argument but before the closing parenthesis is owned by the last Arg if it exists.

class libcst.Arg[source]

A single argument to a Call.

This supports named keyword arguments in the form of keyword=value and variable argument expansion using *args or **kwargs syntax.

value: The argument expression itself, not including a preceding keyword, or any of the surrounding the value, like a comma or asterisks.

keyword: Optional keyword for the argument.

equal: The equal sign used to denote assignment if there is a keyword.

comma: Any trailing comma.

star: A string with zero, one, or two asterisks appearing before the name. These are expanded into variable number of positional or keyword arguments.

whitespace_after_star: Whitespace after the star (if it exists), but before the keyword or value (if no keyword is provided).

whitespace_after_arg: Whitespace after this entire node. The Comma node (if it exists) may also store some trailing whitespace.

Literal Values

class libcst.Ellipsis[source]

An ellipsis .... When used as an expression, it evaluates to the Ellipsis constant. Ellipsis are often used as placeholders in code or in conjunction with SubscriptElement.

lpar

rpar: Sequence of parenthesis for precedence dictation.

Numbers

class libcst.BaseNumber[source]: A type such as Integer, Float, or Imaginary that can be used anywhere that you need to explicitly take any number type.

class libcst.Integer[source]

value

A string representation of the integer, such as "100000" or 100_000.

To convert this string representation to an int, use the calculated property evaluated_value.

lpar

rpar: Sequence of parenthesis for precedence dictation.

property evaluated_value: int: Return an ast.literal_eval() evaluated int of value.

class libcst.Float[source]

value

A string representation of the floating point number, such as "0.05", ".050", or "5e-2".

To convert this string representation to an float, use the calculated property evaluated_value.

lpar

rpar: Sequence of parenthesis for precedence dictation.

property evaluated_value: float: Return an ast.literal_eval() evaluated float of value.

class libcst.Imaginary[source]

value

A string representation of the imaginary (complex) number, such as "2j".

To convert this string representation to an complex, use the calculated property evaluated_value.

lpar

rpar: Sequence of parenthesis for precedence dictation.

property evaluated_value: complex: Return an ast.literal_eval() evaluated complex of value.

Strings

class libcst.BaseString[source]: A type that can be used anywhere that you need to take any string. This includes SimpleString, ConcatenatedString, and FormattedString.

class libcst.SimpleString[source]

Any sort of literal string expression that is not a FormattedString (f-string), including triple-quoted multi-line strings.

value: The texual representation of the string, including quotes, prefix characters, and any escape characters present in the original source code , such as r"my string\n". To remove the quotes and interpret any escape characters, use the calculated property evaluated_value.

lpar

rpar: Sequence of parenthesis for precidence dictation.

property prefix: str: Returns the string’s prefix, if any exists. The prefix can be r, u, b, br or rb.

property quote: Literal['"', "'", '"""', "'''"]: Returns the quotation used to denote the string. Can be either ', ", ''' or """.

property raw_value: str: Returns the raw value of the string as it appears in source, without the beginning or end quotes and without the prefix. This is often useful when constructing transforms which need to manipulate strings in source code.

property evaluated_value: str: Return an ast.literal_eval() evaluated str of value.

class libcst.ConcatenatedString[source]

Represents an implicitly concatenated string, such as:

"abc" "def" == "abcdef"

Warning

This is different from two strings joined in a BinaryOperation with an Add operator, and is sometimes viewed as an antifeature of Python.

left: String on the left of the concatenation.

right: String on the right of the concatenation.

lpar

rpar: Sequence of parenthesis for precidence dictation.

whitespace_between: Whitespace between the left and right substrings.

property evaluated_value: Optional[str]: Return an ast.literal_eval() evaluated str of recursively concatenated left and right if and only if both left and right are composed by SimpleString or ConcatenatedString (FormattedString cannot be evaluated).

Formatted Strings (f-strings)

class libcst.FormattedString[source]

An “f-string”. These formatted strings are string literals prefixed by the letter “f”. An f-string may contain interpolated expressions inside curly braces ({ and }).

F-strings are defined in PEP 498 and documented in Python’s language reference.

>>> import libcst as cst
>>> cst.parse_expression('f"ab{cd}ef"')
FormattedString(
    parts=[
        FormattedStringText(
            value='ab',
        ),
        FormattedStringExpression(
            expression=Name(
                value='cd',
                lpar=[],
                rpar=[],
            ),
            conversion=None,
            format_spec=None,
            whitespace_before_expression=SimpleWhitespace(
                value='',
            ),
            whitespace_after_expression=SimpleWhitespace(
                value='',
            ),
        ),
        FormattedStringText(
            value='ef',
        ),
    ],
    start='f"',
    end='"',
    lpar=[],
    rpar=[],
)

parts: A formatted string is composed as a series of FormattedStringText and FormattedStringExpression parts.

start: The string prefix and the leading quote, such as f", F', fr", or f""".

end: The trailing quote. This must match the type of quote used in start.

lpar

rpar: Sequence of parenthesis for precidence dictation.

property prefix: str: Returns the string’s prefix, if any exists. The prefix can be f, fr, or rf.

property quote: Literal['"', "'", '"""', "'''"]: Returns the quotation used to denote the string. Can be either ', ", ''' or """.

class libcst.BaseFormattedStringContent[source]: The base type for FormattedStringText and FormattedStringExpression. A FormattedString is composed of a sequence of BaseFormattedStringContent parts.

class libcst.FormattedStringText[source]

Part of a FormattedString that is not inside curly braces ({ or }). For example, in:

f"ab{cd}ef"

ab and ef are FormattedStringText nodes, but {cd} is a FormattedStringExpression.

value: The raw string value, including any escape characters present in the source code, not including any enclosing quotes.

class libcst.FormattedStringExpression[source]

Part of a FormattedString that is inside curly braces ({ or }), including the surrounding curly braces. For example, in:

f"ab{cd}ef"

{cd} is a FormattedStringExpression, but ab and ef are FormattedStringText nodes.

An f-string expression may contain conversion and format_spec suffixes that control how the expression is converted to a string. See Python’s language reference for details.

expression: The expression we will evaluate and render when generating the string.

conversion: An optional conversion specifier, such as !s, !r or !a.

format_spec: An optional format specifier following the format specification mini-language.

whitespace_before_expression: Whitespace after the opening curly brace ({), but before the expression.

whitespace_after_expression: Whitespace after the expression, but before the conversion, format_spec and the closing curly brace (}). Python does not allow whitespace inside or after a conversion or format_spec.

equal: Equal sign for formatted string expression uses self-documenting expressions, such as f"{x=}". See the Python 3.8 release notes.

Collections

Simple Collections

class libcst.Tuple[source]

An immutable literal tuple. Tuples are often (but not always) parenthesized.

Tuple([
    Element(Integer("1")),
    Element(Integer("2")),
    StarredElement(Name("others")),
])

generates the following code:

(1, 2, *others)

elements: A sequence containing all the Element and StarredElement nodes in the tuple.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.BaseList[source]

A base class for List and ListComp, which both result in a list object when evaluated.

lbracket: libcst._nodes.expression.LeftSquareBracket = Field(name=None,type=None,default=<dataclasses._MISSING_TYPE object>,default_factory=<function CSTNode.field.<locals>.<lambda>>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=<dataclasses._MISSING_TYPE object>,_field_type=None)

rbracket: libcst._nodes.expression.RightSquareBracket = Field(name=None,type=None,default=<dataclasses._MISSING_TYPE object>,default_factory=<function CSTNode.field.<locals>.<lambda>>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=<dataclasses._MISSING_TYPE object>,_field_type=None): Brackets surrounding the list.

lpar: Sequence[libcst._nodes.expression.LeftParen] = ()

rpar: Sequence[libcst._nodes.expression.RightParen] = (): Sequence of parenthesis for precedence dictation.

class libcst.List[source]

A mutable literal list.

List([
    Element(Integer("1")),
    Element(Integer("2")),
    StarredElement(Name("others")),
])

generates the following code:

[1, 2, *others]

List comprehensions are represented with a ListComp node.

elements: A sequence containing all the Element and StarredElement nodes in the list.

lbracket

rbracket: Brackets surrounding the list.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.BaseSet[source]: An abstract base class for Set and SetComp, which both result in a set object when evaluated.

class libcst.Set[source]

A mutable literal set.

Set([
    Element(Integer("1")),
    Element(Integer("2")),
    StarredElement(Name("others")),
])

generates the following code:

{1, 2, *others}

Set comprehensions are represented with a SetComp node.

elements: A sequence containing all the Element and StarredElement nodes in the set.

lbrace

rbrace: Braces surrounding the set.

lpar

rpar: Sequence of parenthesis for precedence dictation.

Simple Collection Elements

class libcst.BaseElement[source]: An element of a literal list, tuple, or set. For elements of a literal dict, see BaseDictElement.

class libcst.Element[source]

A simple value in a literal List, Tuple, or Set. These a literal collection may also contain a StarredElement.

If you’re using a literal Dict, see DictElement instead.

value

comma: A trailing comma. By default, we’ll only insert a comma if one is required.

class libcst.StarredElement[source]

A starred *value element that expands to represent multiple values in a literal List, Tuple, or Set.

If you’re using a literal Dict, see StarredDictElement instead.

If this node owns parenthesis, those parenthesis wrap the leading asterisk, but not the trailing comma. For example:

StarredElement(
    cst.Name("el"),
    comma=cst.Comma(),
    lpar=[cst.LeftParen()],
    rpar=[cst.RightParen()],
)

will generate:

(*el),

value

comma: A trailing comma. By default, we’ll only insert a comma if one is required.

lpar: Parenthesis at the beginning of the node, before the leading asterisk.

rpar: Parentheses after the value, but before a comma (if there is one).

whitespace_before_value: Whitespace between the leading asterisk and the value expression.

Dictionaries

class libcst.BaseDict[source]: An abstract base class for Dict and DictComp, which both result in a dict object when evaluated.

class libcst.Dict[source]

A literal dictionary. Key-value pairs are stored in elements using DictElement nodes.

It’s possible to expand one dictionary into another, as in {k: v, **expanded}. Expanded elements are stored as StarredDictElement nodes.

Dict([
    DictElement(Name("k1"), Name("v1")),
    DictElement(Name("k2"), Name("v2")),
    StarredDictElement(Name("expanded")),
])

generates the following code:

{k1: v1, k2: v2, **expanded}

elements

lbrace

rbrace: Braces surrounding the set or dict.

lpar

rpar: Sequence of parenthesis for precedence dictation.

Dictionary Elements

class libcst.BaseDictElement[source]: An element of a literal dict. For elements of a list, tuple, or set, see BaseElement.

class libcst.DictElement[source]

A simple key: value pair that represents a single entry in a literal Dict. Dict nodes may also contain a StarredDictElement.

If you’re using a literal List, Tuple, or Set, see Element instead.

key

value

comma: A trailing comma. By default, we’ll only insert a comma if one is required.

whitespace_before_colon: Whitespace after the key, but before the colon in key : value.

whitespace_after_colon: Whitespace after the colon, but before the value in key : value.

class libcst.StarredDictElement[source]

A starred **value element that expands to represent multiple values in a literal Dict.

If you’re using a literal List, Tuple, or Set, see StarredElement instead.

Unlike StarredElement, this node does not own left or right parenthesis, but the value field may still contain parenthesis. This is due to some asymmetry in Python’s grammar.

value

comma: A trailing comma. By default, we’ll only insert a comma if one is required.

whitespace_before_value: Whitespace between the leading asterisks and the value expression.

Comprehensions

class libcst.BaseComp[source]

A base class for all comprehension and generator expressions, including GeneratorExp, ListComp, SetComp, and DictComp.

for_in: libcst._nodes.expression.CompFor

class libcst.BaseSimpleComp[source]

The base class for ListComp, SetComp, and GeneratorExp. DictComp is not a BaseSimpleComp, because it uses key and value.

elt: libcst._nodes.expression.BaseAssignTargetExpression: The expression evaluated during each iteration of the comprehension. This lexically comes before the for_in clause, but it is semantically the inner-most element, evaluated inside the for_in clause.

for_in: libcst._nodes.expression.CompFor: The for ... in ... if ... clause that lexically comes after elt. This may be a nested structure for nested comprehensions. See CompFor for details.

class libcst.GeneratorExp[source]

A generator expression. elt represents the value yielded for each item in CompFor.iter.

All for ... in ... and if ... clauses are stored as a recursive CompFor data structure inside for_in.

elt: The expression evaluated and yielded during each iteration of the generator.

for_in: The for ... in ... if ... clause that comes after elt. This may be a nested structure for nested comprehensions. See CompFor for details.

lpar

rpar: Sequence of parentheses for precedence dictation. Generator expressions must always be parenthesized. However, if a generator expression is the only argument inside a function call, the enclosing Call node may own the parentheses instead.

class libcst.ListComp[source]

A list comprehension. elt represents the value stored for each item in CompFor.iter.

All for ... in ... and if ... clauses are stored as a recursive CompFor data structure inside for_in.

elt: The expression evaluated and stored during each iteration of the comprehension.

for_in: The for ... in ... if ... clause that comes after elt. This may be a nested structure for nested comprehensions. See CompFor for details.

lbracket

rbracket: Brackets surrounding the list comprehension.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.SetComp[source]

A set comprehension. elt represents the value stored for each item in CompFor.iter.

All for ... in ... and if ... clauses are stored as a recursive CompFor data structure inside for_in.

elt: The expression evaluated and stored during each iteration of the comprehension.

for_in: The for ... in ... if ... clause that comes after elt. This may be a nested structure for nested comprehensions. See CompFor for details.

lbrace

rbrace: Braces surrounding the set comprehension.

lpar

rpar: Sequence of parenthesis for precedence dictation.

class libcst.DictComp[source]

A dictionary comprehension. key and value represent the dictionary entry evaluated for each item.

All for ... in ... and if ... clauses are stored as a recursive CompFor data structure inside for_in.

key: The key inserted into the dictionary during each iteration of the comprehension.

value: The value associated with the key inserted into the dictionary during each iteration of the comprehension.

for_in: The for ... in ... if ... clause that lexically comes after key and value. This may be a nested structure for nested comprehensions. See CompFor for details.

lbrace

rbrace: Braces surrounding the dict comprehension.

lpar

rpar: Sequence of parenthesis for precedence dictation.

whitespace_before_colon: Whitespace after the key, but before the colon in key : value.

whitespace_after_colon: Whitespace after the colon, but before the value in key : value.

class libcst.CompFor[source]

One for clause in a BaseComp, or a nested hierarchy of for clauses.

Nested loops in comprehensions are difficult to get right, but they can be thought of as a flat representation of nested clauses.

elt for a in b for c in d if e can be thought of as:

for a in b:
    for c in d:
        if e:
            yield elt

And that would form the following CST:

ListComp(
    elt=Name("elt"),
    for_in=CompFor(
        target=Name("a"),
        iter=Name("b"),
        ifs=[],
        inner_comp_for=CompFor(
            target=Name("c"),
            iter=Name("d"),
            ifs=[
                CompIf(
                    test=Name("e"),
                ),
            ],
        ),
    ),
)

Normal for statements are provided by For.

target: The target to assign a value to in each iteration of the loop. This is different from GeneratorExp.elt, ListComp.elt, SetComp.elt, and key and value in DictComp, because it doesn’t directly effect the value of resulting generator, list, set, or dict.

iter: The value to iterate over. Every value in iter is stored in target.

ifs

Zero or more conditional clauses that control this loop. If any of these tests fail, the target item is skipped.

if a if b if c

has similar semantics to:

if a and b and c

inner_for_in: Another CompFor node used to form nested loops. Nested comprehensions can be useful, but they tend to be difficult to read and write. As a result they are uncommon.

asynchronous: An optional async modifier that appears before the for keyword.

whitespace_before: Whitespace that appears at the beginning of this node, before the for and async keywords.

whitespace_after_for: Whitespace appearing after the for keyword, but before the target.

whitespace_before_in: Whitespace appearing after the target, but before the in keyword.

whitespace_after_in: Whitespace appearing after the in keyword, but before the iter.

class libcst.CompIf[source]

A conditional clause in a CompFor, used as part of a generator or comprehension expression.

If the test fails, the current element in the CompFor will be skipped.

test: An expression to evaluate. When interpreted, Python will coerce it to a boolean.

whitespace_before: Whitespace before the if keyword.

whitespace_before_test: Whitespace after the if keyword, but before the test expression.

Subscripts and Slices

class libcst.Subscript[source]

A indexed subscript reference (Index) such as x[2], a Slice such as x[1:-1], or an extended slice (SubscriptElement) such as x[1:2, 3].

value: The left-hand expression which, when evaluated, will be subscripted, such as x in x[2].

slice: The SubscriptElement to extract from the value.

lbracket

rbracket: Brackets after the value surrounding the slice.

lpar

rpar: Sequence of parenthesis for precedence dictation.

whitespace_after_value: Whitespace after the value, but before the lbracket.

class libcst.BaseSlice[source]: Any slice type that can slot into a SubscriptElement. This node is purely for typing.

class libcst.Index[source]

Any index as passed to a Subscript. In x[2], this would be the 2 value.

value: The index value itself.

class libcst.Slice[source]

Any slice operation in a Subscript, such as 1:, 2:3:4, etc.

Note that the grammar does NOT allow parenthesis around a slice so they are not supported here.

lower: The lower bound in the slice, if present

upper: The upper bound in the slice, if present

step: The step in the slice, if present

first_colon: The first slice operator

second_colon: The second slice operator, usually omitted

class libcst.SubscriptElement[source]

Part of a sequence of slices in a Subscript, such as 1:2, 3. This is not used in Python’s standard library, but it is used in some third-party libraries. For example, NumPy uses it to select values and ranges from multi-dimensional arrays.

slice: A slice or index that is part of a subscript.

comma: A separating comma, with any whitespace it owns.

Parenthesis, Brackets, and Braces

class libcst.LeftParen[source]

Used by various nodes to denote a parenthesized section. This doesn’t own the whitespace to the left of it since this is owned by the parent node.

whitespace_after: Any space that appears directly after this left parenthesis.

class libcst.RightParen[source]

Used by various nodes to denote a parenthesized section. This doesn’t own the whitespace to the right of it since this is owned by the parent node.

whitespace_before: Any space that appears directly after this left parenthesis.

class libcst.LeftSquareBracket[source]

Used by various nodes to denote a subscript or list section. This doesn’t own the whitespace to the left of it since this is owned by the parent node.

whitespace_after: Any space that appears directly after this left square bracket.

class libcst.RightSquareBracket[source]

Used by various nodes to denote a subscript or list section. This doesn’t own the whitespace to the right of it since this is owned by the parent node.

whitespace_before: Any space that appears directly before this right square bracket.

class libcst.LeftCurlyBrace[source]

Used by various nodes to denote a dict or set. This doesn’t own the whitespace to the left of it since this is owned by the parent node.

whitespace_after: Any space that appears directly after this left curly brace.

class libcst.RightCurlyBrace[source]

Used by various nodes to denote a dict or set. This doesn’t own the whitespace to the right of it since this is owned by the parent node.

whitespace_before: Any space that appears directly before this right curly brace.

Statements

Statements represent a “line of code” or a control structure with other lines of code, such as an If block.

All statements subclass from BaseSmallStatement or BaseCompoundStatement.

Statements can be parsed with parse_statement() or as part of a module using parse_module().

Simple Statements

Statements which at most have expressions as child attributes.

class libcst.BaseSmallStatement[source]

Encapsulates a small statement, like del or pass, and optionally adds a trailing semicolon. A small statement is always contained inside a SimpleStatementLine or SimpleStatementSuite. This exists to simplify type definitions and isinstance checks.

semicolon: Union[libcst._nodes.op.Semicolon, libcst._maybe_sentinel.MaybeSentinel] = 1: An optional semicolon that appears after a small statement. This is optional for the last small statement in a SimpleStatementLine or SimpleStatementSuite, but all other small statements inside a simple statement must contain a semicolon to disambiguate multiple small statements on the same line.

class libcst.AnnAssign[source]

An assignment statement such as x: int = 5 or x: int. This only allows for one assignment target unlike Assign but it includes a variable annotation. Also unlike Assign, the assignment target is optional, as it is possible to annotate an expression without assigning to it.

target: The target that is being annotated and possibly assigned to.

annotation: The annotation for the target.

value: The optional expression being assigned to the target.

equal: The equals sign used to denote assignment if there is a value.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Assert[source]

An assert statement such as assert x > 5 or assert x > 5, 'Uh oh!'

test: The test we are going to assert on.

msg: The optional message to display if the test evaluates to a falsey value.

comma: A comma separating test and message, if there is a message.

whitespace_after_assert: Whitespace appearing after the assert keyword and before the test.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Assign[source]

An assignment statement such as x = y or x = y = z. Unlike AnnAssign, this does not allow type annotations but does allow for multiple targets.

targets: One or more targets that are being assigned to.

value: The expression being assigned to the targets.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.AugAssign[source]

An augmented assignment statement, such as x += 5.

target: Target that is being operated on and assigned to.

operator: The augmented assignment operation being performed.

value: The value used with the above operator to calculate the new assignment.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Break[source]

Represents a break statement, which is used to break out of a For or While loop early.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Continue[source]

Represents a continue statement, which is used to skip to the next iteration in a For or While loop.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Del[source]

Represents a del statement. del is always followed by a target.

target: The target expression will be deleted. This can be a name, a tuple, an item of a list, an item of a dictionary, or an attribute.

whitespace_after_del: The whitespace after the del keyword.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Expr[source]

An expression used as a statement, where the result is unused and unassigned. The most common place you will find this is in function calls where the return value is unneeded.

value: The expression itself. Python will evaluate the expression but not assign the result anywhere.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Global[source]

A global statement.

names: A list of one or more names.

whitespace_after_global: Whitespace appearing after the global keyword and before the first name.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Import[source]

An import statement.

names: One or more names that are being imported, with optional local aliases.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

whitespace_after_import: The whitespace that appears after the import keyword but before the first import alias.

class libcst.ImportFrom[source]

A from x import y statement.

module: Name or Attribute node representing the module we’re importing from. This is optional as ImportFrom allows purely relative imports.

names: One or more names that are being imported from the specified module, with optional local aliases.

relative: Sequence of Dot nodes indicating relative import level.

lpar: Optional open parenthesis for multi-line import continuation.

rpar: Optional close parenthesis for multi-line import continuation.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

whitespace_after_from: The whitespace that appears after the from keyword but before the module and any relative import dots.

whitespace_before_import: The whitespace that appears after the module but before the import keyword.

whitespace_after_import: The whitespace that appears after the import keyword but before the first import name or optional left paren.

class libcst.Nonlocal[source]

A nonlocal statement.

names: A list of one or more names.

whitespace_after_nonlocal: Whitespace appearing after the global keyword and before the first name.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Pass[source]

Represents a pass statement.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Raise[source]

A raise exc or raise exc from cause statement.

exc: The exception that we should raise.

cause: Optionally, a from cause clause to allow us to raise an exception out of another exception’s context.

whitespace_after_raise: Any whitespace appearing between the raise keyword and the exception.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

class libcst.Return[source]

Represents a return or a return x statement.

value: The optional expression that will be evaluated and returned.

whitespace_after_return: Optional whitespace after the return keyword before the optional value expression.

semicolon: Optional semicolon when this is used in a statement line. This semicolon owns the whitespace on both sides of it when it is used.

Compound Statements

Statements that have one or more statement blocks as a child attribute.

class libcst.BaseCompoundStatement[source]

Encapsulates a compound statement, like if True: pass or while True: pass. This exists to simplify type definitions and isinstance checks.

Compound statements contain (groups of) other statements; they affect or control the execution of those other statements in some way. In general, compound statements span multiple lines, although in simple incarnations a whole compound statement may be contained in one line.

—https://docs.python.org/3/reference/compound_stmts.html

body: libcst._nodes.statement.BaseSuite: The body of this compound statement.

leading_lines: Sequence[libcst._nodes.whitespace.EmptyLine]: Any empty lines or comments appearing before this statement.

class libcst.ClassDef[source]

A class definition.

name: The class name.

body: The class body.

bases: Sequence of base classes this class inherits from.

keywords: Sequence of keywords, such as “metaclass”.

decorators: Sequence of decorators applied to this class.

lpar: Optional open parenthesis used when there are bases or keywords.

rpar: Optional close parenthesis used when there are bases or keywords.

leading_lines: Leading empty lines and comments before the first decorator. We assume any comments before the first decorator are owned by the class definition itself. If there are no decorators, this will still contain all of the empty lines and comments before the class definition.

lines_after_decorators: Empty lines and comments between the final decorator and the ClassDef node. In the case of no decorators, this will be empty.

whitespace_after_class: Whitespace after the class keyword and before the class name.

whitespace_after_name: Whitespace after the class name and before the opening parenthesis for the bases and keywords.

whitespace_before_colon: Whitespace after the closing parenthesis or class name and before the colon.

get_docstring(clean: bool = True) → Optional[str][source]: Returns a inspect.cleandoc() cleaned docstring if the docstring is available, None otherwise.

class libcst.For[source]

A for target in iter statement.

target: The target of the iterator in the for statement.

iter: The iterable expression we will loop over.

body: The suite that is wrapped with this statement.

orelse: An optional else case which will be executed if there is no Break statement encountered while looping.

asynchronous: Optional async modifier, if this is an async for statement.

leading_lines: Sequence of empty lines appearing before this for statement.

whitespace_after_for: Whitespace after the for keyword and before the target.

whitespace_before_in: Whitespace after the target and before the in keyword.

whitespace_after_in: Whitespace after the in keyword and before the iter.

whitespace_before_colon: Whitespace after the iter and before the colon.

class libcst.FunctionDef[source]

A function definition.

name: The function name.

params: The function parameters. Present even if there are no params.

body: The function body.

decorators: Sequence of decorators applied to this function. Decorators are listed in order that they appear in source (top to bottom) as apposed to the order that they are applied to the function at runtime.

returns: An optional return annotation, if the function is annotated.

asynchronous: Optional async modifier, if this is an async function.

leading_lines: Leading empty lines and comments before the first decorator. We assume any comments before the first decorator are owned by the function definition itself. If there are no decorators, this will still contain all of the empty lines and comments before the function definition.

lines_after_decorators: Empty lines and comments between the final decorator and the FunctionDef node. In the case of no decorators, this will be empty.

whitespace_after_def: Whitespace after the def keyword and before the function name.

whitespace_after_name: Whitespace after the function name and before the opening parenthesis for the parameters.

whitespace_before_params: Whitespace after the opening parenthesis for the parameters but before the first param itself.

whitespace_before_colon: Whitespace after the closing parenthesis or return annotation and before the colon.

get_docstring(clean: bool = True) → Optional[str][source]: When docstring is available, returns a inspect.cleandoc() cleaned docstring. Otherwise, returns None.

class libcst.If[source]

An if statement. test holds a single test expression.

elif clauses don’t have a special representation in the AST, but rather appear as extra If nodes within the orelse section of the previous one.

test: The expression that, when evaluated, should give us a truthy/falsey value.

body: The body of this compound statement.

orelse: An optional elif or else clause. If signifies an elif block. Else signifies an else block. None signifies no else or elif block.

leading_lines: Sequence of empty lines appearing before this compound statement line.

whitespace_before_test: The whitespace appearing after the if keyword but before the test expression.

whitespace_after_test: The whitespace appearing after the test expression but before the colon.

class libcst.Try[source]

A try statement.

body: The suite that is wrapped with a try statement.

handlers: A list of zero or more exception handlers.

orelse: An optional else case.

finalbody: An optional finally case.

leading_lines: Sequence of empty lines appearing before this compound statement line.

whitespace_before_colon: The whitespace that appears after the try keyword but before the colon.

class libcst.While[source]

A while statement.

test: The test we will loop against.

body: The suite that is wrapped with this statement.

orelse: An optional else case which will be executed if there is no Break statement encountered while looping.

leading_lines: Sequence of empty lines appearing before this while statement.

whitespace_after_while: Whitespace after the while keyword and before the test.

whitespace_before_colon: Whitespace after the test and before the colon.

class libcst.With[source]

A with statement.

items: A sequence of one or more items that evaluate to context managers.

body: The suite that is wrapped with this statement.

asynchronous: Optional async modifier if this is an async with statement.

leading_lines: Sequence of empty lines appearing before this with statement.

whitespace_after_with: Whitespace after the with keyword and before the first item.

whitespace_before_colon: Whitespace after the last item and before the colon.

Helper Nodes

Nodes that are used by various statements to represent some syntax, but are not statements on their own and cannot be used outside of the statements they belong with.

class libcst.Annotation[source]

An annotation for a function (PEP 3107) or on a variable (PEP 526). Typically these are used in the context of type hints (PEP 484), such as:

# a variable with a type
good_ideas: List[str] = []

# a function with type annotations
def concat(substrings: Sequence[str]) -> str:
    ...

annotation: The annotation’s value itself. This is the part of the annotation after the colon or arrow.

whitespace_before_indicator

whitespace_after_indicator

class libcst.AsName[source]

An as name clause inside an ExceptHandler, ImportAlias or WithItem node.

name: Identifier that the parent node will be aliased to.

whitespace_before_as: Whitespace between the parent node and the as keyword.

whitespace_after_as: Whitespace between the as keyword and the name.

class libcst.AssignTarget[source]

A target for an Assign. Owns the equals sign and the whitespace around it.

target: The target expression being assigned to.

whitespace_before_equal: The whitespace appearing before the equals sign.

whitespace_after_equal: The whitespace appearing after the equals sign.

class libcst.BaseAssignTargetExpression[source]

An expression that’s valid on the left side of an assignment. That assignment may be part an Assign node, or it may be part of a number of other control structures that perform an assignment, such as a For loop.

Python’s grammar defines all expression as valid in this position, but the AST compiler further restricts the allowed types, which is what this type attempts to express.

This is similar to a BaseDelTargetExpression, but it also includes StarredElement as a valid node.

The set of valid nodes are defined as part of CPython’s AST context computation.

class libcst.BaseDelTargetExpression[source]

An expression that’s valid on the right side of a Del statement.

Python’s grammar defines all expression as valid in this position, but the AST compiler further restricts the allowed types, which is what this type attempts to express.

This is similar to a BaseAssignTargetExpression, but it excludes StarredElement.

The set of valid nodes are defined as part of CPython’s AST context computation and as part of CPython’s bytecode compiler.

class libcst.Decorator[source]

A single decorator that decorates a FunctionDef or a ClassDef.

decorator: The decorator that will return a new function wrapping the parent of this decorator.

leading_lines: Line comments and empty lines before this decorator. The parent FunctionDef or ClassDef node owns leading lines before the first decorator so that if the first decorator is removed, spacing is preserved.

whitespace_after_at: Whitespace after the @ and before the decorator expression itself.

trailing_whitespace: Optional trailing comment and newline following the decorator before the next line.

class libcst.Else[source]

An else clause that appears optionally after an If, While, Try, or For statement.

This node does not match elif clauses in If statements. It also does not match the required else clause in an IfExp expression (a = if b else c).

body: The body of else clause.

leading_lines: Sequence of empty lines appearing before this compound statement line.

whitespace_before_colon: The whitespace appearing after the else keyword but before the colon.

class libcst.ExceptHandler[source]

An except clause that appears optionally after a Try statement.

body: The body of the except.

type: The type of exception this catches. Can be a tuple in some cases, or None if the code is catching all exceptions.

name: The optional name that a caught exception is assigned to.

leading_lines: Sequence of empty lines appearing before this compound statement line.

whitespace_after_except: The whitespace between the except keyword and the type attribute.

whitespace_before_colon: The whitespace after any type or name node (whichever comes last) and the colon.

class libcst.Finally[source]

A finally clause that appears optionally after a Try statement.

body: The body of the except.

leading_lines: Sequence of empty lines appearing before this compound statement line.

whitespace_before_colon: The whitespace that appears after the finally keyword but before the colon.

class libcst.ImportAlias[source]

An import, with an optional AsName. Used in both Import and ImportFrom to specify a single import out of another module.

name: Name or Attribute node representing the object we are importing.

asname: Local alias we will import the above object as.

comma: Any trailing comma that appears after this import. This is optional for the last ImportAlias in a Import or ImportFrom, but all other import aliases inside an import must contain a comma to disambiguate multiple imports.

property evaluated_name: str: Returns the string name this ImportAlias represents.

property evaluated_alias: Optional[str]: Returns the string name for any alias that this ImportAlias has. If there is no asname attribute, this returns None.

class libcst.NameItem[source]

A single identifier name inside a Global or Nonlocal statement.

This exists because a list of names in a global or nonlocal statement need to be separated by a comma, which ends up owned by the NameItem node.

name: Identifier name.

comma: This is forbidden for the last NameItem in a Global/Nonlocal, but all other tems inside a global or nonlocal statement must contain a comma to separate them.

class libcst.Parameters[source]

A function or lambda parameter list.

params: Positional parameters, with or without defaults. Positional parameters with defaults must all be after those without defaults.

star_arg

kwonly_params: Keyword-only params that may or may not have defaults.

star_kwarg: Optional parameter that captures unspecified kwargs.

posonly_params: Positional-only parameters, with or without defaults. Positional-only parameters with defaults must all be after those without defaults.

posonly_ind: Optional sentinel that dictates parameters preceeding are positional-only args.

class libcst.Param[source]

A positional or keyword argument in a Parameters list. May contain an Annotation and, in some cases, a default.

name: The parameter name itself.

annotation: Any optional Annotation. These annotations are usually used as type hints.

equal: The equal sign used to denote assignment if there is a default.

default: Any optional default value, used when the argument is not supplied.

comma: A trailing comma. If one is not provided, MaybeSentinel will be replaced with a comma only if a comma is required.

star: Zero, one, or two asterisks appearing before name for Param’s star_arg and star_kwarg.

whitespace_after_star: The whitespace before name. It will appear after star when a star exists.

whitespace_after_param: The whitespace after this entire node.

class libcst.ParamSlash[source]

A sentinel indicator on a Parameters list to denote that the previous params are positional-only args.

This syntax is described in PEP 570.

comma

class libcst.ParamStar[source]

A sentinel indicator on a Parameters list to denote that the subsequent params are keyword-only args.

This syntax is described in PEP 3102.

comma

class libcst.WithItem[source]

A single context manager in a With block, with an optional variable name.

item: Expression that evaluates to a context manager.

asname: Variable to assign the context manager to, if it is needed in the With body.

comma: This is forbidden for the last WithItem in a With, but all other items inside a with block must contain a comma to separate them.

Statement Blocks

Nodes that represent some group of statements.

class libcst.BaseSuite[source]

A dummy base-class for both SimpleStatementSuite and IndentedBlock. This exists to simplify type definitions and isinstance checks.

A suite is a group of statements controlled by a clause. A suite can be one or more semicolon-separated simple statements on the same line as the header, following the header’s colon, or it can be one or more indented statements on subsequent lines.

—https://docs.python.org/3/reference/compound_stmts.html

body: Union[Sequence[libcst._nodes.statement.BaseStatement], Sequence[libcst._nodes.statement.BaseSmallStatement]]

class libcst.SimpleStatementLine[source]

A simple statement that’s part of an IndentedBlock or Module. A simple statement is a series of small statements joined together by semicolons.

This isn’t differentiated from a SimpleStatementSuite in the grammar, but because a SimpleStatementLine can own additional whitespace that a SimpleStatementSuite doesn’t have, we’re differentiating it in the CST.

body: Sequence of small statements. All but the last statement are required to have a semicolon.

leading_lines: Sequence of empty lines appearing before this simple statement line.

trailing_whitespace: Any optional trailing comment and the final NEWLINE at the end of the line.

class libcst.SimpleStatementSuite[source]

A simple statement that’s used as a suite. A simple statement is a series of small statements joined together by semicolons. A suite is the thing that follows the colon in a compound statement.

if test:<leading_whitespace><body><trailing_whitespace>

This isn’t differentiated from a SimpleStatementLine in the grammar, but because the two classes need to track different whitespace, we’re differentiating it in the CST.

body: Sequence of small statements. All but the last statement are required to have a semicolon.

leading_whitespace: The whitespace between the colon in the parent statement and the body.

trailing_whitespace: Any optional trailing comment and the final NEWLINE at the end of the line.

class libcst.IndentedBlock[source]

Represents a block of statements beginning with an INDENT token and ending in a DEDENT token. Used as the body of compound statements, such as an if statement’s body.

A common alternative to an IndentedBlock is a SimpleStatementSuite, which can also be used as a BaseSuite, meaning that it can be used as the body of many compound statements.

An IndentedBlock always occurs after a colon in a BaseCompoundStatement, so it owns the trailing whitespace for the compound statement’s clause.

if test: # IndentedBlock's header
    body

body: Sequence of statements belonging to this indented block.

header: Any optional trailing comment and the final NEWLINE at the end of the line.

indent: A string represents a specific indentation. A None value uses the modules’s default indentation. This is included because indentation is allowed to be inconsistent across a file, just not ambiguously.

footer: Any trailing comments or lines after the dedent that are owned by this indented block. Statements own preceeding and same-line trailing comments, but not trailing lines, so it falls on IndentedBlock to own it. In the case that a statement follows an IndentedBlock, that statement will own the comments and lines that are at the same indent as the statement, and this IndentedBlock will own the comments and lines that are indented further.

Operators

Nodes that are used to signify an operation to be performed on a variable or value.

Unary Operators

Nodes that are used with UnaryOperation to perform some unary operation.

class libcst.BitInvert

class libcst.Minus

class libcst.Not

class libcst.Plus[source]

A unary operator that can be used in a UnaryOperation expression.

whitespace_after: Any space that appears directly after this operator.

In addition, BaseUnaryOp is defined purely for typing and isinstance checks.

class libcst.BaseUnaryOp

Boolean Operators

Nodes that are used with BooleanOperation to perform some boolean operation.

class libcst.And

class libcst.Or[source]

A boolean operator that can be used in a BooleanOperation expression.

whitespace_before: Any space that appears directly before this operator.

whitespace_after: Any space that appears directly after this operator.

In addition, BaseBooleanOp is defined purely for typing and isinstance checks.

class libcst.BaseBooleanOp

Binary Operators

Nodes that are used with BinaryOperation to perform some binary operation.

class libcst.Add

class libcst.BitAnd

class libcst.BitOr

class libcst.BitXor

class libcst.Divide

class libcst.FloorDivide

class libcst.LeftShift

class libcst.MatrixMultiply

class libcst.Modulo

class libcst.Multiply

class libcst.Power

class libcst.RightShift

class libcst.Subtract[source]

A binary operator that can be used in a BinaryOperation expression.

whitespace_before: Any space that appears directly before this operator.

whitespace_after: Any space that appears directly after this operator.

In addition, BaseBinaryOp is defined purely for typing and isinstance checks.

class libcst.BaseBinaryOp

Comparison Operators

Nodes that are used with Comparison to perform some comparison operation.

class libcst.Equal

class libcst.GreaterThan

class libcst.GreaterThanEqual

class libcst.In

class libcst.Is

class libcst.LessThan

class libcst.LessThanEqual[source]

A comparision operator that can be used in a Comparison expression.

whitespace_before: Any space that appears directly before this operator.

whitespace_after: Any space that appears directly after this operator.

class libcst.NotEqual[source]

A comparison operator that can be used in a Comparison expression.

This node defines a static value for convenience, but in reality due to PEP 401 it can be one of two values, both of which should be a NotEqual Comparison operator.

value: The actual text value of this operator. Can be either != or <>.

whitespace_before: Any space that appears directly before this operator.

whitespace_after: Any space that appears directly after this operator.

class libcst.IsNot

class libcst.NotIn[source]

A comparision operator that can be used in a Comparison expression.

This operator spans two tokens that must be separated by at least one space, so there is a third whitespace attribute to represent this.

whitespace_before: Any space that appears directly before this operator.

whitespace_between: Any space that appears between the not and in tokens.

whitespace_after: Any space that appears directly after this operator.

In addition, BaseCompOp is defined purely for typing and isinstance checks.

class libcst.BaseCompOp

Augmented Assignment Operators

Nodes that are used with AugAssign to perform some agumented assignment.

class libcst.AddAssign

class libcst.BitAndAssign

class libcst.BitOrAssign

class libcst.BitXorAssign

class libcst.DivideAssign

class libcst.FloorDivideAssign

class libcst.LeftShiftAssign

class libcst.MatrixMultiplyAssign

class libcst.ModuloAssign

class libcst.MultiplyAssign

class libcst.PowerAssign

class libcst.RightShiftAssign

class libcst.SubtractAssign[source]

An augmented assignment operator that can be used in a AugAssign statement.

whitespace_before: Any space that appears directly before this operator.

whitespace_after: Any space that appears directly after this operator.

In addition, BaseAugOp is defined purely for typing and isinstance checks.

class libcst.BaseAugOp

Miscellaneous

Miscelaneous nodes that are purely syntactic trivia. While python requires these nodes in order to parse a module, statement or expression they do not carry any meaning on their own.

class libcst.AssignEqual[source]

Used by AnnAssign to denote a single equal character when doing an assignment on top of a type annotation. Also used by Param and Arg to denote assignment of a default value, and by FormattedStringExpression to denote usage of self-documenting expressions.

whitespace_before: Any space that appears directly before this equal sign.

whitespace_after: Any space that appears directly after this equal sign.

class libcst.Colon[source]

Used by Slice as a separator between subsequent expressions, and in Lambda to separate arguments and body.

whitespace_before: Any space that appears directly before this colon.

whitespace_after: Any space that appears directly after this colon.

class libcst.Comma[source]

Syntactic trivia used as a separator between subsequent items in various parts of the grammar.

Some use-cases are:

Import or ImportFrom.
FunctionDef arguments.
Tuple/List/Set/Dict elements.

whitespace_before: Any space that appears directly before this comma.

whitespace_after: Any space that appears directly after this comma.

class libcst.Dot[source]

Used by Attribute as a separator between subsequent Name nodes.

whitespace_before: Any space that appears directly before this dot.

whitespace_after: Any space that appears directly after this dot.

class libcst.ImportStar[source]: Used by ImportFrom to denote a star import instead of a list of importable objects.

class libcst.Semicolon[source]

Used by any small statement (any subclass of BaseSmallStatement such as Pass) as a separator between subsequent nodes contained within a SimpleStatementLine or SimpleStatementSuite.

whitespace_before: Any space that appears directly before this semicolon.

whitespace_after: Any space that appears directly after this semicolon.

Whitespace

Nodes that encapsulate pure whitespace.

class libcst.Comment[source]

A comment including the leading pound (#) character.

The leading pound character is included in the ‘value’ property (instead of being stripped) to help re-enforce the idea that whitespace immediately after the pound character may be significant. E.g:

# comment with whitespace at the start (usually preferred)
#comment without whitespace at the start (usually not desirable)

Usually wrapped in a TrailingWhitespace or EmptyLine node.

value: The comment itself. Valid values start with the pound (#) character followed by zero or more non-newline characters. Comments cannot include newlines.

class libcst.EmptyLine[source]

Represents a line with only whitespace/comments. Usually statements will own any EmptyLine nodes above themselves, and a Module will own the document’s header/footer EmptyLine nodes.

indent: An empty line doesn’t have to correspond to the current indentation level. For example, this happens when all trailing whitespace is stripped and there is an empty line between two statements.

whitespace: Extra whitespace after the indent, but before the comment.

comment: An optional comment appearing after the indent and extra whitespace.

newline: The newline character that terminates this empty line.

class libcst.Newline[source]

Represents the newline that ends an EmptyLine or a statement (as part of TrailingWhitespace).

Other newlines may occur in the document after continuation characters (the backslash, \), but those newlines are treated as part of the SimpleWhitespace.

Optionally, a value can be specified in order to overwrite the module’s default newline. In general, this should be left as the default, which is None. This is allowed because python modules are permitted to mix multiple unambiguous newline markers.

value: A value of None indicates that the module’s default newline sequence should be used. A value of \n or \r\n indicates that the exact value specified will be used for this newline.

class libcst.ParenthesizedWhitespace[source]

This is the kind of whitespace you might see inside a parenthesized expression or statement between two tokens when there is a newline without a line continuation (\) character.

https://docs.python.org/3/reference/lexical_analysis.html#implicit-line-joining

A parenthesized whitespace cannot be empty since it requires at least one TrailingWhitespace. If you have whitespace that does not contain comments or newlines, use SimpleWhitespace instead.

first_line: The whitespace that comes after the previous node, up to and including the end-of-line comment and newline.

empty_lines: Any lines after the first that contain only indentation and/or comments.

indent: Whether or not the final simple whitespace is indented regularly.

last_line: Extra whitespace after the indent, but before the next node.

property empty: bool: Indicates that this node is empty (zero whitespace characters). For ParenthesizedWhitespace this will always be False.

class libcst.SimpleWhitespace[source]

This is the kind of whitespace you might see inside the body of a statement or expression between two tokens. This is the most common type of whitespace.

A simple whitespace cannot contain a newline character unless it is directly preceeded by a line continuation character (\). It can contain zero or more spaces or tabs. If you need a newline character without a line continuation character, use ParenthesizedWhitespace instead.

Simple whitespace is often non-semantic (optional), but in cases where whitespace solves a grammar ambiguity between tokens (e.g. if test, versus iftest), it has some semantic value.

An example SimpleWhitespace containing a space, a line continuation, a newline and another space is as follows:

SimpleWhitespace(r" \\n ")

value: Actual string value of the simple whitespace. A legal value contains only space, \f and \t characters, and optionally a continuation (\) followed by a newline (\n or \r\n).

property empty: bool: Indicates that this node is empty (zero whitespace characters).

class libcst.TrailingWhitespace[source]

The whitespace at the end of a line after a statement. If a line contains only whitespace, EmptyLine should be used instead.

whitespace: Any simple whitespace before any comment or newline.

comment: An optional comment appearing after any simple whitespace.

newline: The newline character that terminates this trailing whitespace.

class libcst.BaseParenthesizableWhitespace[source]

This is the kind of whitespace you might see inside the body of a statement or expression between two tokens. This is the most common type of whitespace.

The list of allowed characters in a whitespace depends on whether it is found inside a parenthesized expression or not. This class allows nodes which can be found inside or outside a (), [] or {} section to accept either whitespace form.

https://docs.python.org/3/reference/lexical_analysis.html#implicit-line-joining

Parenthesizable whitespace may contain a backslash character (\), when used as a line-continuation character. While the continuation character isn’t technically “whitespace”, it serves the same purpose.

Parenthesizable whitespace is often non-semantic (optional), but in cases where whitespace solves a grammar ambiguity between tokens (e.g. if test, versus iftest), it has some semantic value.

abstract property empty: bool: Indicates that this node is empty (zero whitespace characters).

Maybe Sentinel

class libcst.MaybeSentinel[source]

A MaybeSentinel value is used as the default value for some attributes to denote that when generating code (when Module.code is evaluated) we should optionally include this element in order to generate valid code.

MaybeSentinel is only used for “syntactic trivia” that most users shouldn’t care much about anyways, like commas, semicolons, and whitespace.

For example, a function call’s Arg.comma value defaults to MaybeSentinel.DEFAULT. A comma is required after every argument, except for the last one. If a comma is required and Arg.comma is a MaybeSentinel, one is inserted.

This makes manual node construction easier, but it also means that we safely add arguments to a preexisting function call without manually fixing the commas:

>>> import libcst as cst
>>> fn_call = cst.parse_expression("fn(1, 2)")
>>> new_fn_call = fn_call.with_changes(
...     args=[*fn_call.args, cst.Arg(cst.Integer("3"))]
... )
>>> dummy_module = cst.parse_module("")  # we need to use Module.code_for_node
>>> dummy_module.code_for_node(fn_call)
'fn(1, 2)'
>>> dummy_module.code_for_node(new_fn_call)
'fn(1, 2, 3)'

Notice that a comma was automatically inserted after the second argument. Since the original second argument had no comma, it was initialized to MaybeSentinel.DEFAULT. During the code generation of the second argument, a comma was inserted to ensure that the resulting code is valid.

Warning

While this sentinel is used in place of nodes, it is not a CSTNode, and will not be visited by a CSTVisitor.

Some other libraries, like RedBaron, take other approaches to this problem. RedBaron’s tree is mutable (LibCST’s tree is immutable), and so they’re able to solve this problem with “proxy lists”. Both approaches come with different sets of tradeoffs.

DEFAULT = 1