fst.fst

Create a new individual FST node or full tree. The main way to use this constructor is as a shortcut for FST.fromsrc(), FST.fromast() or FST.as_(), the usage is:

FST(src_or_ast_or_fst, mode=None)

This will create an FST from either an AST or source code in the form of a string or list of lines, or it will attempt to coerce an existing FST to the type you want specified by mode.

WARNING! In normal usage, you should always leave pfield at its default as anything else will select other modes of opertation for this constructor.

Parameters:

• src_or_ast_or_fst: Source code or an AST or FST node.
• mode: See fst.parsex.Mode. Has the following meanings when the src_or_ast_or_fst parameter is:
  • src: If mode is None then we will try to guess what the source is and parse it accordingly. If specified then will attempt to parse this type and if fails then the exception will propagate. If guessing then it may take more than one attempt so it is always better to specify what you expect to get if you know it.
  • AST: If mode is None then defaults to the type of the AST, which will always succeed in generating valid source unless the AST itself is in an invalid state (like an empty Set). Anything else you pass here will be passed on as the mode to fromast(). In which case if the AST is this then the FST tree is just build for it and otherwise coercion will be attempted to this type.
  • FST: mode should be specified and will be the type of node you want to coerce the FST you pass in to. If you leave it at the default None then you will just get either the same FST or a copy of it, depending on the copy kwarg.
• kwargs: options if coercing from another FST or extra parameters, mostly for internal use documented below. One extra parameter relevant to this use case is:
  • copy: If coercing from another FST, this parameter is what will be passed to as_(). It defaults to True here so that FST(other_FST) works in the same way as list(other_list), meaning it doesn't alter the source object, which is the opposite of what the default for the as_() function is.

Examples:

>>> FST('def f(): call()\ndef g(): pass')
<Module ROOT 0,0..1,13>

Minimal node representation is created by default, so stmt instead of mod if possible and expr instead of stmt.

>>> FST('def f(): call()')
<FunctionDef ROOT 0,0..0,15>

>>> FST('call()')
<Call ROOT 0,0..0,6>

You can force a module.

>>> FST('call()', 'exec')
<Module ROOT 0,0..0,6>

Can parse things not normally parsable.

>>> FST('start:stop:step')
<Slice ROOT 0,0..0,15>

FST guesses what you want in this case but doesn't always get it right.

>>> FST('start:stop')
<AnnAssign ROOT 0,0..0,10>

So you can tell it. This is also usually faster to parse than if fst has to guess and try parsing something that it is not before finding out what it is, so if this is important to you then always pass the type you expect to get when you can.

>>> FST('start:stop', 'Slice')
<Slice ROOT 0,0..0,10>

You can tell it to only parse things which are top-level parsable by ast.parse().

>>> try:
...     FST('start:stop:step', 'strict')
... except Exception as exc:
...     print(str(exc))
invalid syntax (<FST>, line 1)

You can also pass an AST and the source will be generated from it.

>>> FST(ast.Slice(Constant(1), Constant(2), Constant(3)))
<Slice ROOT 0,0..0,5>

>>> print(_.src)
1:2:3

Coercion is straightforward.

>>> f = FST('expr')
>>> f, f.src
(<Name ROOT 0,0..0,4>, 'expr')

>>> g = FST(f, 'stmt')
>>> g, g.src
(<Expr ROOT 0,0..0,4>, 'expr')

>>> g = FST(f, 'Name')
>>> g, g.src, g is f
(<Name ROOT 0,0..0,4>, 'expr', False)

Turn off copy to return the same node if it is the type you are requesting.

>>> g = FST(f, 'Name', copy=False)
>>> g, g.src, g is f
(<Name ROOT 0,0..0,4>, 'expr', True)

But still coerces if is not.

>>> g = FST(f, 'arg', copy=False)
>>> g, g.src, g is f
(<arg ROOT 0,0..0,4>, 'expr', False)

Same options apply as to all other operations.

>>> FST(FST('[]'), 'Set').src  # will give invalid empty Set node
'{}'

>>> FST(FST('[]'), 'Set', norm=True).src
'{*()}'

The other forms of this function are meant for internal use, their parameters are below for reference just in case:

Parameters:

• src_or_ast_or_fst: AST node for FST or source code in the form of a str or a list of lines. If an AST then will be processed differently depending on if creating child node, top level node or using this as a shortcut for a full fromsrc() or fromast(). If left as empty default then just creates a new empty Module.
• mode: Is really mode_or_lines_or_parent. Parent node for this child node or lines for a root node creating a new tree. If pfield is False then this is a shortcut to create a full tree from an AST node or source provided in src_or_ast_or_fst.
• pfield: fst.common.astfield indication position in parent of this node. If provided then creating a simple child node and it is created with the self.parent set to mode node and self.pfield set to this. If None then it means the creation of a full new FST tree and this is the root node with mode providing the source. If False then this is a shortcut for FST.fromsrc() or FST.fromast().
• kwargs: Contextual parameters:
  • from_: If this is provided then it must be an FST node from which this node is being created. This allows to copy parse parameters and already determined default indentation. Does not have to be root.
  • parse_params: A dict with values for filename, type_comments and feature_version which will be used for any AST reparse done on this tree. Only valid when creating a root node.
  • indent: Indentation string to use as default indentation. If not provided and not gotten from from_ then indentation will be inferred from source. Only valid when creating a root node.
  • filename, type_comments and feature_version: If creating from an AST or source only then these are the parameteres passed to the respective .fromsrc() or .fromast() functions. Only valid when pfield is False, meaning a shortcut use of FST().
  • lcopy: Whether to copy lines of source on root node create or just use what is passed in, which in this case must be a list of fst.astutil.bistr and this node takes ownership of the list.
  • tmake: Whether to do _make_fst_tree() on self or not. Turning this off can be used to create a root node for a specific existing FST tree. Useful for optimizing some operations.

The actual AST node. Will be set to None for FST nodes which were deleted or otherwise invalidated so can be checked for that to see if the FST is still alive (while walking and modifying for example).

Parent FST node, None in root node.

The fst.common.astfield location of this node in the parent, None in root node.

The parameters to use for any ast.parse() (filename, type_comments, feature_version). Exists mostly for passing filename and future-proofing.

The default single level block indentation string for this tree when not available from context.

Allows to quickly differentiate between actual FST nodes vs. views or locations.

True if the node is part of a tree, False if has been replaced or removed.

True for the root node, False otherwise.

Root node of the tree this node belongs to.

Whole lines of this node from the RAW SOURCE, without any dedentation, may also contain parts of enclosing nodes. Will have indentation as it appears in the top level source if multiple lines. If gotten at root then the entire source is returned, which may extend beyond the location of the top-level node (mostly for statements which may have leading / trailing comments or empty lines).

A valid list of strings is always returned, even for nodes which can never have source like Load, etc... The lines list returned is always a copy so safe to modify.

WARNING! You get just the text that is there so you will get unparsable source if you get for example a string Constant from the values field of a JoinedStr, or a format_spec.

Source code of this node from the RAW SOURCE clipped out as a single string, without any dedentation. Will have indentation as it appears in the top level source if multiple lines. If gotten at root then the entire source is returned, regardless of whether the actual top level node location includes it or not.

A string is always returned, even for nodes which can never have source like Load, etc...

WARNING! You get just the text that is there so you will get unparsable source if you get for example a string Constant from the values field of a JoinedStr, or a format_spec.

True when the node has its own location which comes directly from AST lineno and other location fields. Otherwise False if no loc or loc is calculated.

Whole source location, from (0, 0) to end of source. Works from any node (not just root).

Zero based character indexed location of node (may not be entire location if node has decorators). Not all nodes have locations (like expr_context). Other nodes which normally don't have locations like arguments or most operators have this location calculated from their children or source.

Note: Empty arguments do NOT have a location even though the AST exists, while non-empty arguments have a calculated location.

Bounding location of node. For non-statements or non-block statements is same as loc. For block statements will include any leading decorators and a trailing line comment on the last child (or self if no children).

Examples:

>>> f = FST('''
... @decorator
... def func():
...     pass  # comment
... '''.strip())

>>> f.bloc
fstloc(0, 0, 2, 19)

>>> f.loc
fstloc(1, 0, 2, 8)

>>> f = FST('stmt  # comment')

Non-block statement doesn't include line comment.

>>> f.bloc
fstloc(0, 0, 0, 4)

Line number of the first line of this node (0 based).

CHARACTER index of the start of this node (0 based).

Line number of the LAST LINE of this node (0 based).

CHARACTER index one past the end of this node (0 based).

Line number of the first line of this node or the first decorator if present (0 based).

CHARACTER column of this node or the first decorator if present (0 based).

Line number of the last line of this node.

CHARACTER column of the end of the last line of this node, past a trailing line comment on last child if self is a block statement.

AST-style line number of the first line of this node (1 based), available for all nodes which have loc (otherwise None).

AST-style BYTE index of the start of this node (0 based), available for all nodes which have loc (otherwise None).

AST-style line number of the LAST LINE of this node (1 based), available for all nodes which have loc (otherwise None).

AST-style BYTE index one past the end of this node (0 based), available for all nodes which have loc (otherwise None).

Indicates whether this node has a docstring. Can only be True for FunctionDef, AsyncFunctionDef, ClassDef or Module. For quick use as start index.

Parse and create a new FST tree from source, preserving the original source and locations.

WARNING! The type_comments parameter is False by default and no guarantees are made if you turn it on. It is provided just in case but really shouldn't be used as fst takes care of comments anyway, this just turns on storing the comments in the AST nodes which may cause all sorts of madness like duplication on unparse or nodes failing to reparse to themselves on operations.

Parameters:

• src: The source to parse as a single str or list of individual line strings (without newlines).
• mode: Parse mode, extended ast.parse() parameter, see fst.parsex.Mode. If you know what kind of node you are expecting then it is always better to pass in this parameter because otherwise several different parse attempts may be made to try to find the type.
• filename: ast.parse() parameter.
• type_comments: ast.parse() parameter. Don't use this, see warning above.
• feature_version: ast.parse() parameter. Don't use this either, here just in case.

Returns:

• FST: The parsed tree with .f attributes added to each AST node for FST access.

Examples:

>>> _ = FST.fromsrc('var').dump()
Module - ROOT 0,0..0,3
  .body[1]
   0] Expr - 0,0..0,3
     .value Name 'var' Load - 0,0..0,3

>>> _ = FST.fromsrc('var', mode='stmt').dump()
Expr - ROOT 0,0..0,3
  .value Name 'var' Load - 0,0..0,3

>>> _ = FST.fromsrc('var', mode='expr').dump()
Name 'var' Load - ROOT 0,0..0,3

>>> _ = FST.fromsrc('except Exception: pass', 'ExceptHandler').dump()
ExceptHandler - ROOT 0,0..0,22
  .type Name 'Exception' Load - 0,7..0,16
  .body[1]
   0] Pass - 0,18..0,22

>>> _ = FST.fromsrc('case f(a=1): pass', 'match_case').dump()
match_case - ROOT 0,0..0,17
  .pattern MatchClass - 0,5..0,11
    .cls Name 'f' Load - 0,5..0,6
    .kwd_attrs[1]
     0] 'a'
    .kwd_patterns[1]
     0] MatchValue - 0,9..0,10
       .value Constant 1 - 0,9..0,10
  .body[1]
   0] Pass - 0,13..0,17

>>> import ast
>>> _ = FST.fromsrc('a:b', ast.Slice).dump()
Slice - ROOT 0,0..0,3
  .lower Name 'a' Load - 0,0..0,1
  .upper Name 'b' Load - 0,2..0,3

Convert an AST tree to a full FST tree. This can take the existing node and just create the FST nodes for it (unparsing to get source code). Or if mode is specified, will try to coerce the AST node to this type and create the FST tree for that.

The passed ast node is not actually consumed. It is unparsed and reparsed to a new AST since we need to make sure the locations are all correct.

WARNING! The type_comments parameter is False by default and no guarantees are made if you turn it on. It is provided just in case but really shouldn't be used as fst takes care of comments anyway, this just turns on storing the comments in the AST nodes which may cause all sorts of madness like duplication on unparse or nodes failing to reparse to themselves on operations.

Parameters:

• ast: The root AST node. This is NOT consumed and will NOT become the actual AST node of the FST tree.
• mode: Parse mode to enable coercion, see fst.parsex.Mode. If None then will just use the given ast type and make an FST using that type.
• coerce: This exists to allow you to turn OFF coercion for some reason as by default coerce is attempted.
• filename: ast.parse() parameter.
• type_comments: ast.parse() parameter. Don't use this, see warning above.
• feature_version: ast.parse() parameter. Don't use this either, here just in case.

Returns:

• FST: The augmented tree with .f attributes added to each AST node for FST access.

Examples:

>>> import ast
>>> from ast import Assign, Constant, List, Name, Slice

>>> _ = FST.fromast(Assign(targets=[Name(id='var')],
...                        value=Constant(value=123))).dump('stmt')
0: var = 123
Assign - ROOT 0,0..0,9
  .targets[1]
   0] Name 'var' Store - 0,0..0,3
  .value Constant 123 - 0,6..0,9

>>> _ = FST.fromast(Slice(lower=Constant(value=1),
...                       step=Name(id='step'))).dump('node')
0: 1::step
Slice - ROOT 0,0..0,7
0: 1
  .lower Constant 1 - 0,0..0,1
0:    step
  .step Name 'step' Load - 0,3..0,7

>>> _ = FST.fromast(List(elts=[Name(id='var')]),
...                 'pattern', coerce=True).dump('stmt')
0: [var]
MatchSequence - ROOT 0,0..0,5
  .patterns[1]
   0] MatchAs - 0,1..0,4
     .name 'var'

>>> _ = FST.fromast(List(elts=[Name(id='var')]),
...                 'pattern', coerce=False).dump('stmt')
Traceback (most recent call last):
...
fst.NodeError: expecting pattern, got List, coerce disabled

>>> _ = FST.fromast(ast.parse('if 1:\n    j = 5')).dump('stmt')
Module - ROOT 0,0..1,9
  .body[1]
0: if 1:
   0] If - 0,0..1,9
     .test Constant 1 - 0,3..0,4
     .body[1]
1:     j = 5
      0] Assign - 1,4..1,9
        .targets[1]
         0] Name 'j' Store - 1,4..1,5
        .value Constant 5 - 1,8..1,9

Get a dictionary of ALL global options. These are the same options that can be passed to operations and this function returns their global defaults which are used when those options are not passed to operations or if they are passed with a value of None

Returns:

• {option: value, ...}: Dictionary of all global default options.

Examples:

>>> from pprint import pp
>>> pp(FST.get_options())
{'raw': False,
 'trivia': True,
 'coerce': True,
 'elif_': True,
 'pep8space': True,
 'docstr': True,
 'pars': 'auto',
 'pars_walrus': False,
 'pars_arglike': True,
 'norm': False,
 'norm_self': None,
 'norm_get': None,
 'set_norm': 'star',
 'op_side': 'left',
 'args_as': None}

Get a single option from options dict or global default if option not in dict or is None there. For a list of options used see options().

Parameters:

• option: Name of option to get.
• options: Dictionary which may or may not contain the requested option.

Returns:

• object: The option value from the passed options dict, if passed and not None there, else the global default value for option.

Examples:

>>> FST.get_option('pars')
'auto'

>>> FST.get_option('pars', {'pars': True})
True

Set global defaults for options parameters.

Parameters:

• options: Names / values of parameters to set. These can also be passed to various methods to override the defaults set here for those individual operations, see options().

Returns:

• old_options: dict of previous values of changed parameters, reset with set_options(**old_options).

Examples:

>>> FST.get_option('pars')
'auto'

>>> FST.set_options(pars=False)
{'pars': 'auto'}

>>> FST.get_option('pars')
False

>>> FST.set_options(**{'pars': 'auto'})
{'pars': False}

>>> FST.get_option('pars')
'auto'

>>> FST.set_options(pars=True, raw=True, docstr=False)
{'pars': 'auto', 'raw': False, 'docstr': True}

Context manager to temporarily set specified global options defaults for a group of operations.

WARNING! Only the options specified in the call to this function will be returned to their original values when the context manager exits. Any other global options changed inside the context block will continue to have those values on context manager exit.

Options:

• raw: When to do raw source operations. This may result in more nodes changed than just the targeted one(s).
  • False: Do not do raw source operations. DEFAULT
  • True: Only do raw source operations.
  • 'auto': Only do raw source operations if the normal operation fails in a way that raw might not.
• trivia: What comments and empty lines to copy / delete / overwrite when doing operations on elements which may have leading or trailing comments and / or empty lines. These are the values as interpreted WHEN SET GLOBALLY. If passed as a parameter to a function then if a non-tuple is passed then that becomes the leading trivia parameter. If a tuple is passed then both the leading and trailing from the tuple are used, unless they are None in which case the global value for that particular parameter is used.
  • False: Same as (False, 'line').
  • True: Same as ('block', 'line'). DEFAULT
  • 'all': Same as ('all', 'line').
  • 'block': Same as ('block', 'line').
  • (leading, trailing): Tuple specifying individual behavior for leading and trailing trivia. The text options can also have a suffix of the form '+/-[#]', meaning plus or minus an optional integer which indicates to include this number of leading / trailing empty lines in the trivia. The values for each element of the tuple can be:
    • False: Don't copy / delete / overwrite any trivia.
    • True: Means 'block' for leading trivia, 'line' for trailing.
    • 'all[+/-[#]]': Copy / delete / overwrite all leading or trailing comments regardless of if they are contiguous or not.
    • 'block[+/-[#]]': Copy / delete / overwrite a single contiguous leading or trailing block of comments where an empty line ends the block.
    • 'line': Only valid for trailing trivia, means just the comment on the last line of the element. Except for block statements where the last line is a child node where that comment belongs to the child regardless of this parameter and so will be copied / deleted / overwritten along with the block.
    • int: A specific line number (starting at 0) indicating the first or last line that can be copied / deleted / overwritten. If not interrupted by other code, will always return from / to this line inclusive. For trailing trivia, if this number is the last line of the element (where the line comment resides) then it will include that tail line comment. If it is BEFORE that line then the line comment will not be included.
• coerce: Whether to allow coercion between compatible AST / FST node types on put. For example allow put a non-slice expr as a slice to something that expects a slice of exprs or allowing use of arg where arguments is expected.
  • False: Do not allow node type coercion, meant for strict type control.
  • True: Allow coercion between similar types. DEFAULT
• elif_: How to handle lone If statements as the only statements in an If statement orelse field.
  • False: Always put as a standalone If statement on put.
  • True: If putting a single If statement to an orelse field of a parent If statement then put it as an elif. DEFAULT
• pep8space: Preceding and trailing empty lines for function and class definitions.
  • False: No empty lines.
  • True: Two empty lines at module scope and one empty line in other scopes. DEFAULT
  • 1: One empty line in all scopes.
• docstr: Which docstrings are indentable / dedentable.
  • False: None.
  • True: All Expr string constants (as they serve no other coding purpose). DEFAULT
  • 'strict': Only string constants in expected docstring positions (functions, classes and top of module).
• pars: How parentheses are handled, can be False, True or 'auto'. This is for individual element operations, slice operations ignore this for the most part as parentheses usually cannot be removed or may need to be added to keep the slices usable. Raw puts generally do not have parentheses added or removed automatically, except maybe removed according to this from the destination node if putting to a node instead of a pure location. See below for pars behavior matrix.
  • False: Parentheses are not MODIFIED, doesn't mean remove all parentheses. Not copied with nodes or removed on put from destination or source. Using incorrectly can result in invalid trees.
  • True: Parentheses are copied with nodes, added to copies if needed and not present and removed from destination on put if not needed there (but not removed from source).
  • 'auto': Same as True except they are not copied with nodes and possibly removed from source on put if not needed (removed from destination first if needed and present on both). DEFAULT
• pars_walrus: Whether to ADD parentheses to top level cut / copied NamedExpr nodes or not. If parentheses were already copied due to pars=True then setting this to False will not remove them. This is more of an aesthetic option as fst can deal with unparenthesized walruses at root level.
  • True: Parenthesize cut / copied NamedExpr walrus expressions.
  • False: Do not parenthesize cut / copied NamedExpr walrus expressions. DEFAULT
  • None: Parenthesize according to the pars option (True and 'auto' parenthesize, False does not).
• pars_arglike: Whether to ADD parentheses to argumentlike-only expressions (*not a, *b or c) when cut / copied either as single element or as part of a slice. If parentheses were already present then setting this to False will not remove them. Unlike pars_walrus this is NOT mostly an aesthetic option as unparenthesized arglike-only expressions are invalid everywhere except in Call.args, ClassDef.bases or an unparenthesized Subscript.slice Tuple.
  • True: Parenthesize cut / copied argumentlike expressions. DEFAULT
  • False: Do not parenthesize cut / copied argumentlike expressions.
  • None: Parenthesize according to the pars option (True and 'auto' parenthesize, False does not).
• norm: Default normalize option for return from get() functions and self target. Determines how ASTs which would otherwise be invalid because of an operation are handled. Mostly how zero or sometimes one-length sequences which normally cannot be zero or one length are left or returned, e.g. zero-length Set. This option can be overridden individually for the two cases of norm_self (target) and norm_get (return from any get operation).
  • False: Allow the AST to go to an unsupported length or state and become invalid. A Set will result in empty curlies which reparse to a Dict. A MatchOr can go to 1 or zero length. Other AST types can also go to zero length. Useful for easier editing. DEFAULT
  • True: Do not allow the AST to go to an unsupported length or state. Can result in an exception being thrown if no alternative exists. A Set which results in zero length gets converted to {*()}.
  • str: In some cases an alternate representation can be specified instead of just True, e.g. 'call' for Set operations.
• norm_self: Override for norm which only applies to a target self on which an operation is being carried out. If this is None then norm is used.
• norm_get: Override for norm which only applies to the return value from any get operation. If this is None then norm is used.
• set_norm: The alternate representation for an empty Set normalization by norm. This can also be set to False to disable normalization for all operations on a Set (unless one of the norm options is set to one of these string modes).
  • 'star': Starred sequence {*()} returned or used for empty self. DEFAULT
  • 'call': set() call returned and used for empty self.
  • False: No Set normalization regardless of norm or norm_* options, just leave or return an invalid Set object.
• op_side: When doing slice operations on a BoolOp or a Compare it may be necessary to specify which side operator is to be deleted or inserted before or after. This can take the values of 'left' or 'right' and specifies which side operator to delete for delete operations. For insert operations this specifies whether to insert before an operator 'left' or operand 'right', roughly translating to which side operator is treated as part of the operator+operand unit. This option is treated as a hint and may be overridden by source code passed to the slice operation or slice position constraints, it will never raise an error if set incompatible with what the operation needs. When inserting into a Compare a non-global op option may be necessary to specify extra missing operator to add if a dangling operator is not passed in the source to insert.
  • 'left': Delete preceding operator on left side of slice or insert before preceding operator. DEFAULT
  • 'right': Delete trailing operator on right side of slice or insert after preceding operator.
• args_as: Conversion for argument types on argument node slice operations. This is mostly meant for per-call use but is a global option in order to allow with options(args_as=?): .... When used on a slice get it converts the gotten slice. When used on a slice put, it converts the slice being put before the attempted put.
  • 'pos': Convert all arguments to posonlyargs if possible, if not then error. If vararg or kwarg present then will error.
  • 'arg': Convert all arguments to args if possible, if not then error. A vararg is allowed but if present then will prevent any present kwonlyargs from being converted and in this case will error. If kwarg is present then will error.
  • 'kw': Convert all arguments to kwonlyargs if possible, if not then error. A kwarg is allowed and will not prevent any conversion as it is always follows all other arguments. If vararg is present then will error.
  • 'arg_only': Same as arg except does not allow a vararg and if present will error.
  • 'kw_only': Same as kw except does not allow a kwarg and if present will error.
  • 'pos_maybe': Attempt to convert all arguments to posonlyargs. args can always be converted but if kwonlyargs cannot be because of a vararg or default value incompatibilities then they will not be converted and there will not be an error. kwarg is left in place.
  • 'arg_maybe': Attempt to convert all arguments to args. posonlyargs can always be converted but if kwonlyargs cannot be because of a vararg or default value incompatibilities then they will not be converted and there will not be an error. kwarg is left in place.
  • 'kw_maybe': Attempt to convert all arguments to kwonlyargs. If vararg is present the posonlyargs and args are not converted, but posonlyargs will be converted in this case to args. kwarg is left in place.

Note: pars behavior:

                                                            False      True    'auto'
Copy pars from source on copy / cut:                         no       yes        no
Add pars needed for parsability to copy:                     no       yes       yes
Remove unneeded pars from destination on put:                no       yes       yes
Remove unneeded pars from source on put:                     no        no       yes
Add pars needed for parse / precedence to source on put:     no       yes       yes

Note: trivia text suffix behavior:

• '+[#]' On copy and delete an extra number of lines after any comments specified by the #. If no number is specified and just a '+' then all empty lines will be copied / deleted.
• '-[#]' On delete but not copy, an extra number of lines after any comments specified by the #. If no number is specified and just a '-' then all empty lines will be deleted.

Examples:

>>> print(FST.get_option('pars'), FST.get_option('elif_'))
auto True

>>> with FST.options(pars=False, elif_=False):
...     print(FST.get_option('pars'), FST.get_option('elif_'))
False False

>>> print(FST.get_option('pars'), FST.get_option('elif_'))
auto True

Attempt to coerce self to the type of node given by mode. If self is already the requested type of node at root level then will do nothing and return self. If is not at root level then will copy the node first and then attempt to coerce.

If self is not the type requested then will attempt to coerce, which is a destructive operation to the original node (self) even if it fails, rendering self unusable. For this reason the copy parameter allows you to specify that self must be copied first before coerce is attempted, leaving the original node intact. Note that a copy is always made regardless if self is not a root node so the original node will be unharmed in that case.

Note: If self is a subclass of the type you request then it counts as a match and self is returned unchanged, e.g. Assign and you request a stmt.

Parameters:

• mode: The type of node you want, None means no coerce and just return self, see fst.parsex.Mode.
• copy: This only matters if you are calling this function on a root node, in which case a copy is made before coerce is attempted in order to make sure the node you are calling remains valid.
• options: See options(). These same options will be used for both a possible copy and for coercion.

Returns:

• FST: Coerced node.

Examples:

>>> f = FST('expr')
>>> f
<Name ROOT 0,0..0,4>

>>> (f := f.as_('stmt'))
<Expr ROOT 0,0..0,4>

>>> f.as_('exec')
<Module ROOT 0,0..0,4>

>>> _ = FST('if a if b', '_comprehension_ifs').as_(expr).dump()
Tuple - ROOT 0,0..0,4
  .elts[2]
   0] Name 'a' Load - 0,0..0,1
   1] Name 'b' Load - 0,3..0,4
  .ctx Load

>>> _ = FST('case [a, cls(b)]: pass').pattern.as_(expr).dump()
List - ROOT 0,0..0,11
  .elts[2]
   0] Name 'a' Load - 0,1..0,2
   1] Call - 0,4..0,10
     .func Name 'cls' Load - 0,4..0,7
     .args[1]
      0] Name 'b' Load - 0,8..0,9
  .ctx Load

Force a reparse of this node to synchronize the AST tree with the source in case the source was changed with non-native or non-synchronous operations such as put_src() with only offset. Can use on any node, not just root.

Returns:

• self: New self after reparse, if possible, otherwise None if could not be found. May also be another neighbor node if the source of self was structurally changed too much. If used on root node then self will not change.

Examples:

>>> f = FST('f"{expr}"')

>>> _ = f.dump('stmt', loc=False)  # loc=False because of py < 3.12
0: f"{expr}"
JoinedStr - ROOT
  .values[1]
   0] FormattedValue
     .value Name 'expr' Load
     .conversion -1

>>> f.put_src('=', 0, 7, 0, 7, 'offset')
(0, 8)

>>> _ = f.dump('stmt', loc=False)
0: f"{expr=}"
JoinedStr - ROOT
  .values[1]
   0] FormattedValue
     .value Name 'expr' Load
     .conversion -1

>>> bool(f.verify(raise_=False))
False

>>> f = f.reparse()

>>> bool(f.verify(raise_=False))
True

>>> _ = f.dump('stmt', loc=False)
0: f"{expr=}"
JoinedStr - ROOT
  .values[2]
   0] Constant 'expr='
   1] FormattedValue
     .value Name 'expr' Load
     .conversion 114

Sanity check. Walk the tree and make sure all ASTs have corresponding FST nodes with valid parent / child links, then (optionally) reparse source and make sure parsed tree matches currently stored tree (locations and everything). The reparse can only be carried out on root nodes but the link validation can be done on any level.

SPECIAL SLICEs like _decorator_list will verify ok with reparse but invalid nodes like an empty Set or block statements with empty bodies will not.

Parameters:

• mode: Parse mode to use, otherwise if None then use the top level AST node type for the mode. Depending on how this is set will determine whether the verification is checking if is parsable by python ('exec' or 'strict' for example), or if the node itself is just in a valid state (None specifies this). See fst.parsex.Mode.
• reparse: Whether to reparse the source and compare ASTs (including location). Otherwise the check is limited to a structure check that all children have FST nodes which are all liked correctly to their parents. reparse=True only allowed on root node.
• locs: Whether to compare locations after reparse or not.
• ctx: Whether to compare ctx nodes after reparse or not.
• raise_: Whether to raise an exception on verify failed or return None.

Returns:

• None on failure to verify (if not raise_), otherwise self.

Examples:

>>> FST('var = 123').verify()
<Assign ROOT 0,0..0,9>

>>> FST('a:b:c').verify()
<Slice ROOT 0,0..0,5>

>>> bool(FST('a:b:c').verify('exec', raise_=False))
False

>>> FST('if a if b').verify()
<_comprehension_ifs ROOT 0,0..0,9>

>>> bool(FST('if a if b').verify('strict', raise_=False))
False

>>> (f := FST('a + b')).put_src('-', 0, 2, 0, 3, action=None)
(0, 3)

>>> f.verify()
Traceback (most recent call last):
...
fst.astutil.WalkFail: child classes differ in BinOp.op, Sub vs. Add, locs ('?', '?', '?', '?') / ('?', '?', '?', '?')

Dump a representation of the tree to stdout or other TextIO or return as a str or list[str] of lines, or call a provided function once with each line of the output.

Parameters:

• src: Either what level of source to show along with the nodes or a shorthand string which can specify almost all the formatting parameters as a string of characters.
  • 'stmt' or 'stmt+' means output statement source lines (including ExceptHandler and match_case) or top level source if level is below statement. The + means put all lines of source including non-coding ones so that whole source is shown.
  • 'node' or 'node+' means output source for each individual node. The + means the same as for 'stmt+'.
  • None does not output any source.
  • str: Can be a string for shortcut specification of source and flags by first letter, 's+feL' would be equivalent to .dump(src='stmt+', full=True, expand=True, loc=False).
    • 's' or 's+' means src='stmt' or src='stmt+'
    • 'S' same as 's+'
    • 'n' or 'n+' means src='node' or src='node+'
    • 'N' same as 'N+'
    • 'f' means full=True
    • 'e' means expand=True
    • 'i' means list_indent=indent
    • 'I' means list_indent=False
    • 'L' means loc=False
    • 'c' means color=True
    • 'C' means color=False
• full: If True then will list all fields in nodes including empty ones, otherwise will exclude most empty fields.
• expand: If False then the output is a nice compact representation. If True then it is ugly and wasteful.
• indent: Indentation per level as an integer (number of spaces) or a string.
• list_indent: Extra indentation for elements of lists as an integer or string (added to indent). If True then will be same as indent.
• loc: Whether to dump locations of nodes or not.
• color: True or False means whether to use ANSI color codes or not. If None then will autodetect, which can be overridden with environment variables FORCE_COLOR and NO_COLOR.
• out: 'print' means print to stdout, 'lines' returns a list of lines and 'str' returns a whole string. A TextIO object here will use the write method for each line of output. Otherwise a Callable[[str], None] which is called for each line of output individually. If 'str' or 'lines' then that is returned, otherwise self is returned for chaining.
• eol: What to put at the end of each text line, None means newline for a TextIO out and nothing for other types of out.

Returns:

• str: If was requested with out='str', string of entire dump, lines ended with eol.
• list[str]: If was requested with out='lines', list of lines ended wiith eol.
• self: If out is anything else, for convenience.

Examples:

>>> f = FST('''
... if 1:
...     call(a=b, **c)
... '''.strip())

>>> _ = f.dump()
If - ROOT 0,0..1,18
  .test Constant 1 - 0,3..0,4
  .body[1]
   0] Expr - 1,4..1,18
     .value Call - 1,4..1,18
       .func Name 'call' Load - 1,4..1,8
       .keywords[2]
        0] keyword - 1,9..1,12
          .arg 'a'
          .value Name 'b' Load - 1,11..1,12
        1] keyword - 1,14..1,17
          .value Name 'c' Load - 1,16..1,17

>>> _ = f.dump(src='node', indent=3, list_indent=True)
0: if 1:
If - ROOT 0,0..1,18
0:    1
   .test Constant 1 - 0,3..0,4
   .body[1]
1:     call(a=b, **c)
      0] Expr - 1,4..1,18
         .value Call - 1,4..1,18
1:     call
            .func Name 'call' Load - 1,4..1,8
            .keywords[2]
1:          a=b
               0] keyword - 1,9..1,12
                  .arg 'a'
1:            b
                  .value Name 'b' Load - 1,11..1,12
1:               **c
               1] keyword - 1,14..1,17
1:                 c
                  .value Name 'c' Load - 1,16..1,17

>>> f.dump(out='str')[:64]
'If - ROOT 0,0..1,18\n  .test Constant 1 - 0,3..0,4\n  .body[1]\n   '

>>> from pprint import pp
>>> pp(f.dump('stmt', loc=False, out='lines'))
['0: if 1:',
 'If - ROOT',
 '  .test Constant 1',
 '  .body[1]',
 '1:     call(a=b, **c)',
 '   0] Expr',
 '     .value Call',
 "       .func Name 'call' Load",
 '       .keywords[2]',
 '        0] keyword',
 "          .arg 'a'",
 "          .value Name 'b' Load",
 '        1] keyword',
 "          .value Name 'c' Load"]

Create a checkpoint with data needed for a later reconcile(). After this function is used, no more FST-native modifications should be made to the tree until after the reconcile(). Any changes for the reconcile() to work must be exclusively in the AST tree. If any modifications are made using FST functions then the checkpoint will be invalidated and will need to be recreated if reconcile() is wanted after the modifications.

Returns:

• self

Reconcile self with a previously marked version and return a new valid FST tree. This is meant for allowing non-FST modifications to an FST tree and later converting it to a valid FST tree to preserve as much formatting as possible and maybe continue operating in FST land. Only AST nodes from the original tree carry formatting information, so the more of those are replaced the more formatting is lost.

Note: When replacing the AST nodes, make sure you are replacing the nodes in the actual AST node fields, not the .a attribute in FST nodes, that won't do anything.

Disclaimer: This functionality is still experimental and unfinished so not all comments which should be may be preserved and others may be duplicated.

Parameters:

• trivia_ast_put: The trivia option to use when putting an AST node. Since AST nodes have no trivia in practice this means how much of the existing trivia at the target node is deleted. None means use default.
• trivia_fst_put: The trivia option to use when putting an FST node, which may or may not have attached trivia depending on the trivia_fst_get option. This option only specifies what happens to the target trivia so depending on if the node being put has any it means delete or replace. None means use default.
• trivia_fst_get: The trivia option to use when getting FST nodes for put. This can happen due to nodes completely translated to a place they were not anywhere near or due to movement because of deletions or insertions into the body where the nodes live. None means use default.
• cleanup: By default after a successful reconcile self is cleanued up and no more reconcile can be attempted on it. It can be left in place to continue working on it and reconcile() again by passing cleanup=False but this is not guaranteed to survive further reconcile development.
• options: Only a few options are allowed for reconcile as others are managed during the process. The most useful ones are elif_ and pep8space. See options().

Returns:

• FST: A new valid reconciled FST if possible.

Examples:

>>> f = FST('''
... @decorator  # something
... def function(a: int, b=2)->int:  # blah
...     return a+b  # return this
...
... def other_function(a, b):
...     return a - b  # return that
... '''.strip())

>>> f.mark()
<Module ROOT 0,0..5,31>

>>> f.a.body[0].returns = Name('float')  # pure AST
>>> f.a.body[0].args.args[0].annotation = Name('float')
>>> f.a.body[0].decorator_list[0] = FST('call_decorator(1, 2, 3)').a
>>> f.a.body[1].name = 'last_function'  # can change non-AST
>>> f.a.body[1].body[0] = f.a.body[0].body[0]  # AST from same FST tree
>>> other = FST('def first_function(a, b): return a * b  # yay!')
>>> f.a.body.insert(0, other.a)  # AST from other FST tree

>>> f = f.reconcile(pep8space=1)

>>> print('\n'.join(l or '.' for l in f.lines))  # print this way for doctest
def first_function(a, b): return a * b  # yay!
.
@call_decorator(1, 2, 3)  # something
def function(a: float, b=2)->float:  # blah
    return a+b  # return this
.
def last_function(a, b):
    return a+b  # return this

>>> f.mark()
<Module ROOT 0,0..7,29>

>>> body = f.a.body[1].body
>>> f.a.body[1] = FST('def f(): pass').a
>>> f.a.body[1].body = body

>>> f = f.reconcile(pep8space=1)

>>> print('\n'.join(l or '.' for l in f.lines))
def first_function(a, b): return a * b  # yay!
.
def f():
    return a+b  # return this
.
def last_function(a, b):
    return a+b  # return this

Get a single item or a slice view from the default field of self. This is just an access, not a cut or a copy, so if you want a copy you must explicitly do .copy() on the returned value.

Same as self.default_field[idx].

Note that fstview can also hold references to non-AST lists of items, so keep this in mind when dealing with return values which may be None or may not be FST nodes.

Parameters:

• idx: The index or builtins.slice where to get the element(s) from.

Returns:

• fstview | FST | str | None: Either a single FST node if accessing a single item or a new fstview view according to the slice passed. builtins.str can also be returned from a view of Global.names or None from a Dict.keys.

Examples:

>>> FST('[0, 1, 2, 3]')[1].src
'1'

>>> FST('[0, 1, 2, 3]')[:3]
<<List ROOT 0,0..0,12>.elts[:3] [<Constant 0,1..0,2>, <Constant 0,4..0,5>, <Constant 0,7..0,8>]>

>>> FST('[0, 1, 2, 3]')[:3].copy().src
'[0, 1, 2]'

>>> FST('[0, 1, 2, 3]')[-3:]
<<List ROOT 0,0..0,12>.elts[1:4] [<Constant 0,4..0,5>, <Constant 0,7..0,8>, <Constant 0,10..0,11>]>

>>> FST('def fun(): pass\nclass cls: pass\nvar = val').body[1]
<ClassDef 1,0..1,15>

>>> FST('global a, b, c').names
<<Global ROOT 0,0..0,14>.names ['a', 'b', 'c']>

>>> FST('global a, b, c')[1]
'b'

Set a single item or a slice view in the default field of self.

Same as self.default_field[idx] = code.

Note that fstview can also hold references to non-AST lists of items, so keep this in mind when assigning values.

Parameters:

• idx: The index or builtins.slice where to put the element(s).

Examples:

>>> from fst import FST

>>> (f := FST('[0, 1, 2, 3]'))[1] = '4'; f.src
'[0, 4, 2, 3]'

>>> (f := FST('[0, 1, 2, 3]'))[:3] = '5'; f.src
'[5, 3]'

>>> (f := FST('[0, 1, 2, 3]'))[:3] = '[5]'; f.src
'[[5], 3]'

>>> (f := FST('[0, 1, 2, 3]'))[:3] = '5,'; f.src
'[5, 3]'

>>> (f := FST('[0, 1, 2, 3]'))[-3:] = '6'; f.src
'[0, 6]'

>>> (f := FST('[0, 1, 2, 3]'))[-3:] = '[6]'; f.src
'[0, [6]]'

>>> (f := FST('[0, 1, 2, 3]'))[:] = '7, 8'; f.src
'[7, 8]'

>>> (f := FST('[0, 1, 2, 3]'))[:] = '[7, 8]'; f.src
'[[7, 8]]'

>>> f = FST('[0, 1, 2, 3]')
>>> f[2:2] = f[1:3].copy()
>>> f.src
'[0, 1, 1, 2, 2, 3]'

Delete a single item or a slice from default field of self.

Note that fstview can also hold references to non-AST lists of items, so keep this in mind when assigning values.

Parameters:

• idx: The index or builtins.slice to delete.

Examples:

>>> from fst import FST

>>> del (f := FST('[0, 1, 2, 3]'))[1]; f.src
'[0, 2, 3]'

>>> del (f := FST('[0, 1, 2, 3]'))[:3]; f.src
'[3]'

>>> del (f := FST('[0, 1, 2, 3]'))[-3:]; f.src
'[0]'

>>> del (f := FST('[0, 1, 2, 3]'))[:]; f.src
'[]'

Lines of this node copied out of the tree and dedented as if the node were copied out. Unlike the .lines property these will not contain parts of other nodes.

This function is a faster way to get this if you just want the source over self.copy().lines. The intermediate parameters for getting this are also cached (not the lines themselves), so it is not so expensive to call this repeatedly.

A valid list of strings is always returned, even for nodes which can never have source like Load, etc... The lines list returned is always a copy so safe to modify.

Caveat: There is an actual qualitative difference between this and self.copy().lines, though it is usually inconsequential. The copy operation may carry out some reformatting to make sure the node is presentable at root level (mostly adding parentheses), this function does not do that. It will however convert an elif to an if. The copy also does trivia, we do not here (yet).

WARNING! With the exception of the elif fix, you get just the text that is there so you will get unparsable source if you get for example a string Constant from the values field of a JoinedStr, or a format_spec.

Parameters:

• whole: If at root this determines whether to return the whole source or just the location of the node (which may not be the whole source).
• docstr: How to treat multiline string docstring lines.
  • False: Don't dedent any.
  • True: Dedent all Expr multiline strings (as they serve no coding purpose).
  • 'strict': Only dedent Expr multiline strings in standard docstring locations.
  • None: Use the global default for the docstr option.

Returns:

• list[str]: List of lines belonging to this node dedented or list with one empty string if node does not have location to get source from (unless at root and whole=True, in which case the whole source is returned).

Examples:

>>> f = FST('''
... def func():
...     return ('not_self', [
...         'self1',
...         'self2',
...     ], 'other_not_self',
...     'outside_lines')
... '''.strip())

Notice the indentation comes with it as well as parts of other nodes.

>>> for l in f.body[0].value.elts[1].lines:  # the list node in the return value
...     print(repr(l))
"    return ('not_self', ["
"        'self1',"
"        'self2',"
"    ], 'other_not_self',"

And here it is all cleaned up.

>>> for l in f.body[0].value.elts[1].own_lines():
...     print(repr(l))
'['
"    'self1',"
"    'self2',"
']'

Source of this node as a string copied out of the tree and dedented as if the node were copied out.

This function is a faster way to get this if you just want the source over self.copy().src. The intermediate parameters for getting this are also cached (not the source itself), so it is not so expensive to call this repeatedly.

Here is a rough performance comparison for scale when using the three methods of getting source of the FST.mark() function from this class (py 3.14).

• .src: 532 nanoseconds
• .copy().src: 140 microseconds
• .own_src(): 7.96 microseconds - intermediate parameters not in cache
• .own_src(): 2.43 microseconds - intermediate parameters in cache (second+ time)

A string is always returned, even for nodes which can never have source like Load, etc...

Note: The first line is always completely dedented.

Caveat: There is an actual qualitative difference between this and self.copy().src, though it is usually inconsequential. The copy operation may carry out some reformatting to make sure the node is presentable at root level (mostly adding parentheses), this function does not do that. It will however convert an elif to an if. The copy also does trivia, we do not here (yet).

WARNING! With the exception of the elif fix, you get just the text that is there so you will get unparsable source if you get for example a string Constant from the values field of a JoinedStr, or a format_spec.

Parameters:

• whole: If at root this determines whether to return the whole source or just the location of the node (which may not be the whole source).
• docstr: How to treat multiline string docstring lines.
  • False: Don't dedent any.
  • True: Dedent all Expr multiline strings (as they serve no coding purpose).
  • 'strict': Only dedent Expr multiline strings in standard docstring locations.
  • None: Use the global default for the docstr option.

Returns:

• str: The source of this node dedented as a string or empty string if node does not have location to get source from (unless at root and whole=True, in which case the whole source is returned).

Examples:

>>> f = FST('''
... def func():
...     return ('not_self', [
...         'self1',
...         'self2',
...     ], 'other_not_self',
...     'outside_lines')
... '''.strip())

Notice the indentation comes with it, but not parts of other nodes like for .lines. The first line for .src is also completely dedented just like .own_src().

>>> print(f.body[0].value.elts[1].src)  # the list node in the return value
[
        'self1',
        'self2',
    ]

And here it is all cleaned up.

>>> print(f.body[0].value.elts[1].own_src())
[
    'self1',
    'self2',
]

Unparse the AST tree of self discarding all formatting. The unparse will correctly handle our own SPECIAL SLICE nodes and does a few other minor tweaks like removing parentheses from top-level Tuple which contains Slice nodes.

Returns:

• str: Unparsed source with all formatting lost.

Examples:

>>> f = FST('if a: b=c  # comment')

>>> print(f.src)
if a: b=c  # comment

>>> print(f.ast_src())
if a:
    b = c

>>> f = FST('array[start : stop : step, other_start : other_stop]')

>>> print(ast.unparse(f.slice.a))  # invalid in any universe
(start:stop:step, other_start:other_stop)

>>> print(f.slice.ast_src())
start:stop:step, other_start:other_stop

Copy the AST node tree of this FST node, not including any FST stuff. Use when you just want a copy of the AST tree from this point down.

Needless to say since this just returns an AST all formatting is lost, except that the AST nodes will have the same lineno, col_offset, end_lineno and end_col_offset values as they had in the FST tree.

Returns:

• AST: Copied AST tree from this point down.

Examples:

>>> a = FST('[0, 1, 2, 3]').copy_ast()

>>> print(type(a))
<class 'ast.List'>

>>> print(dump(a))
List(elts=[Constant(value=0), Constant(value=1), Constant(value=2), Constant(value=3)], ctx=Load())

Copy this node to a new top-level tree, dedenting and fixing as necessary. If copying root node then an identical copy is made and no fixes / modifications are applied unless whole=False.

Parameters:

• whole: This only has meaning when copying a root node, otherwise all options rules apply.
  • True: Copies the entire tree and source without any modifications (including leading and trailing source which is not part of the node), no options are honored.
  • False: For statementlike nodes will honor the trivia option and only copy allowed trivia source along with the node. For expressions and patterns the various pars options will be honored and any parentesization which may happen on a normal copy will be carried out as well. For all other node types that have a location will trim away any source that falls outside of the node and only copy the node and its own source.
• options: See options().

Returns:

• FST: Copied node.

Examples:

>>> FST('[a(), b(), c(), d()]').elts[1].copy().src
'b()'

Copies at root are special, default copies everything.

>>> f = FST('''
... # pre
... call()  # tail
... # post
... '''.strip(), 'expr')

>>> print('\n'.join(repr(l) for l in f.copy().lines))
'# pre'
'call()  # tail'
'# post'

>>> print('\n'.join(repr(l) for l in f.copy(whole=False).lines))
'call()'

A module is always copied whole.

>>> f = FST('''
... # pre
... call()  # tail
... # post
... '''.strip(), 'Module')

>>> print('\n'.join(repr(l) for l in f.copy(whole=False).lines))
'# pre'
'call()  # tail'
'# post'

Cut out this node to a new top-level tree (if possible), dedenting and fixing as necessary. Cannot cut root node.

Parameters:

• options: See options().

Returns:

• FST: Cut node.

Examples:

>>> (f := FST('[0, 1, 2, 3]')).elts[1].cut().src
'1'

>>> f.src
'[0, 2, 3]'

Replace or delete (if code=None, if possible) this node. Returns the new node for self, not the old replaced node, or None if was deleted or raw replaced and the old node disappeared. Cannot delete root node. CAN replace root node, in which case self remains the same but the top-level AST and source change.

Note: If replacing root node, the trivia option is not honored.

WARNING! If passing an FST then this is not guaranteed to become the new node (on purpose). If you wish to continue using the FST node you just replaced then make sure to use the one returned from this function. The AST node will also not be identical if coercion happened.

Parameters:

• code: FST, AST or source str or list[str] to put at this location. None to delete this node.
• one: Default True means replace with a single element. If False and field allows it then can replace single element with a slice.
• options: See options().
  • to: Special option which only applies replacing in raw mode (either through True or 'auto'). Instead of replacing just this node, will replace the entire span from this node to the node specified in to with the code passed.

Returns:

• FST or None: Returns the new node if successfully replaced or None if deleted or raw replace and corresponding new node could not be found.

Examples:

>>> FST('[0, 1, 2, 3]').elts[1].replace('4').root.src
'[0, 4, 2, 3]'

>>> f = FST('def f(a, /, b, *c, **d) -> int: pass')

>>> f.args.posonlyargs[0].replace(')', to=f.returns, raw=True)  # raw reparse
<arguments 0,6..0,6>

>>> f.src
'def f(): pass'

Delete this node if possible, equivalent to replace(None, ...). Cannot delete root node.

Parameters:

• options: See options().

Examples:

>>> (f := FST('[0, 1, 2, 3]')).elts[1].remove()
>>> f.src
'[0, 2, 3]'

Insert into field of self at a specific index. Default field if field=None. This is a convenience function for self.put_slice().

Same as self.field.insert().

Returns:

• self

Parameters:

• code: FST, AST or source str or list[str] to insert.
• idx: Index to insert before. Can be 'end' to indicate add at end of slice.
• field: Field to operate on or the default field if is None. Must be a list field.
• one: If True then will insert code as a single item. Otherwise False will attempt a slice insertion (type must be compatible).
• options: See fst.fst.FST.options().

Note: The field value can optionally be passed positionally in the idx parameter. If passed in idx idx is assumed to be 0.

Examples:

>>> from fst import FST

>>> FST('[0, 1, 2, 3]').insert('4, 5', 1).src
'[0, (4, 5), 1, 2, 3]'

>>> FST('[0, 1, 2, 3]').insert('(4, 5)', 1).src
'[0, (4, 5), 1, 2, 3]'

>>> FST('[0, 1, 2, 3]').insert('4, 5', 'end', one=False).src
'[0, 1, 2, 3, 4, 5]'

>>> FST('[0, 1, 2, 3]').insert('(4, 5)', 'end', one=False).src
'[0, 1, 2, 3, (4, 5)]'

>>> # same as 'end' but 'end' is always 'end'
>>> FST('[0, 1, 2, 3]').insert('4, 5', 4, one=False).src
'[0, 1, 2, 3, 4, 5]'

>>> FST('[0, 1, 2, 3]').insert('(4, 5)', 4, one=False).src
'[0, 1, 2, 3, (4, 5)]'

>>> FST('[0, 1, 2, 3]')[1:3].insert('*star').base.src
'[0, *star, 1, 2, 3]'

Append code as a single element to field of self. Default field if field=None. This is a convenience function for self.put_slice().

Same as self.field.append().

Returns:

• self

Parameters:

• code: FST, AST or source str or list[str] to append.
• field: Field to operate on or the default field if is None. Must be a list field.
• options: See fst.fst.FST.options().

Examples:

>>> from fst import FST

>>> FST('[0, 1, 2, 3]').append('(4, 5)').src
'[0, 1, 2, 3, (4, 5)]'

>>> FST('[0, 1, 2, 3]')[1:3].append('*star').base.src
'[0, 1, 2, *star, 3]'

Extend field of self with the slice in code (type must be compatible). Default field if field=None. This is a convenience function for self.put_slice().

Same as self.field.extend().

Returns:

• self

Parameters:

• code: FST, AST or source str or list[str] slice to extend.
• field: Field to operate on or the default field if is None. Must be a list field.
• options: See fst.fst.FST.options().

Examples:

>>> from fst import FST

>>> FST('[0, 1, 2, 3]').extend('4, 5').src
'[0, 1, 2, 3, 4, 5]'

>>> FST('[0, 1, 2, 3]').extend('(4, 5)').src
'[0, 1, 2, 3, (4, 5)]'

>>> FST('[0, 1, 2, 3]')[1:3].extend('4, 5').base.src
'[0, 1, 2, 4, 5, 3]'

>>> FST('[0, 1, 2, 3]')[1:3].extend('(4, 5)').base.src
'[0, 1, 2, (4, 5), 3]'

prepend code as a single element to the beginning of field of self. Default field if field=None. This is a convenience function for self.put_slice().

Same as self.field.prepend().

Returns:

• self

Parameters:

• code: FST, AST or source str or list[str] to preappend.
• options: See fst.fst.FST.options().

Examples:

>>> from fst import FST

>>> FST('[0, 1, 2, 3]').prepend('(4, 5)').src
'[(4, 5), 0, 1, 2, 3]'

>>> FST('[0, 1, 2, 3]')[1:3].prepend('*star').base.src
'[0, *star, 1, 2, 3]'

Extend the beginning of the field of self with the slice in code (type must be compatible). Default field if field=None. This is a convenience function for self.put_slice().

Same as self.field.prextend().

Returns:

• self

Parameters:

• code: FST, AST or source str or list[str] to extend at the start.
• field: Field to operate on or the default field if is None. Must be a list field.
• options: See fst.fst.FST.options().

Examples:

>>> from fst import FST

>>> FST('[0, 1, 2, 3]').prextend('4, 5').src
'[4, 5, 0, 1, 2, 3]'

>>> FST('[0, 1, 2, 3]').prextend('(4, 5)').src
'[(4, 5), 0, 1, 2, 3]'

>>> FST('[0, 1, 2, 3]')[1:3].prextend('4, 5').base.src
'[0, 4, 5, 1, 2, 3]'

>>> FST('[0, 1, 2, 3]')[1:3].prextend('(4, 5)').base.src
'[0, (4, 5), 1, 2, 3]'

Copy or cut an individual child node or a slice of child nodes from self if possible. This function can do everything that get_slice() can do.

Parameters:

• idx: The index of the child node to get if the field being gotten from contains multiple elements or the start of the slice to get if getting a slice (by specifying stop). If the field being gotten from is an individual element then this must be None.
• stop: The end index (exclusive) of the child node to get if getting a slice from a field that contains multiple elements. This should be one past the last element to get (like python list indexing). If the field being gotten from is an individual element then this must be None.
• field: The name of the field to get the element(s) from, which can be an individual element like a value or a list like body. If this is None then the default field for the node type is used. Most node types have a common-sense default field, e.g. body for all block statements, value for things like Return and Yield. Dict, MatchMapping and Compare nodes have special handling for a None field (which defaults to the _all virtual field for them).
• cut: Whether to cut out the child node (if possible) or not (just copy).
• options: See options().

Note: The field value can optionally be passed positionally in either the idx or stop parameter. If passed in idx a value of None is used for idx, which will select either just the element from a single element field or the entire slice from a list field. If passed in stop then the idx value is present and stop is assumed to be None.

Returns:

• FST: When getting an actual node (most situations).
• str: When getting an identifier, like from Name.id.
• constant: When getting a constant (fst.astutil.constant), like from Constant.value or MatchSingleton.value.

Examples:

>>> FST('[0, 1, 2, 3]').get(1).src
'1'

>>> (f := FST('[0, 1, 2, 3]')).get(1, 3).src
'[1, 2]'
>>> f.src
'[0, 1, 2, 3]'

>>> (f := FST('[0, 1, 2, 3]')).get(1, 3, cut=True).src
'[1, 2]'
>>> f.src
'[0, 3]'

>>> FST('[0, 1, 2, 3]').get(0, 3).src
'[0, 1, 2]'

>>> FST('[0, 1, 2, 3]').get(-3, 'end').src
'[1, 2, 3]'

>>> FST('if 1: i = 1\nelse: j = 2').get(0).src
'i = 1'

>>> FST('if 1: i = 1\nelse: j = 2').get('orelse').src
'j = 2'

>>> FST('if 1: i = 1\nelse: j = 2; k = 3').get(1, 'orelse').src
'k = 3'

>>> FST('if 1: i = 1\nelse: j = 2; k = 3; l = 4; m = 5').get(1, 3, 'orelse').src
'k = 3; l = 4'

>>> FST('return 1').get().src  # default field is 'value'
'1'

>>> FST('[0, 1, 2, 3]').get().src  # 'elts' slice copy is made
'[0, 1, 2, 3]'

Put an individual node or a slice of nodes to self if possible. The node is passed as an existing top-level FST, AST, string or list of string lines. If passed as an FST then it should be considered "consumed" after this function returns and should not be accessed again, even on failure. If passed as an AST then it is copied and can be reused after this function returns. This is the most general form of node put function and can do everything that the other node put functions can.

WARNING! The original self node may be invalidated during the operation if using raw mode (either raw=True or if it happened as a fallback from raw='auto'). If there is a possibility of this happening then make sure to use the new self returned from this function, otherwise if no raw happens then self remains unchanged and usable.

Parameters:

• code: The node to put as an FST (must be root node), AST, a string or list of line strings. If putting to an identifier field then this should be a string and it will be taken literally (no parsing). If putting to a constant like MatchSingleton.value or Constant.value then this should be an appropriate primitive constant value.
• idx: The index of the field node to put to if the field being put to contains multiple elements or the start of the slice to put if putting a slice (by specifying stop). If the field being put to is an individual element then this must be None.
• stop: The end index (exclusive) of the field node to put to if putting a slice to a field that contains multiple elements. This should be one past the last element to put (like python list indexing). If the field being put to is an individual element then this must be None.
• field: The name of the field to put the element(s) to, which can be an individual element like a value or a list like body. If this is None then the default field for the node type is used. Most node types have a common-sense default field, e.g. body for all block statements, value for things like Return and Yield. Dict, MatchMapping and Compare nodes have special handling for a None field (which defaults to the _all virtual field for them).
• one: Only has meaning if putting a slice and in this case True specifies that the source should be put as a single element to the range specified even if it is a valid slice. False indicates that a slice value should be put as slice and not an individual element, which must in this case be a compatible slice type.
• options: See options().
  • to: Special option which only applies when putting a single element in raw mode (either through True or 'auto'). Instead of replacing just the target node, will replace the entire span from the target node to the node specified in to with the code passed.

Note: The field value can optionally be passed positionally in either the idx or stop parameter. If passed in idx a value of None is used for idx, which will select either just the element from a single element field or the entire slice from a list field. If passed in stop then the idx value is present and stop is assumed to be None.

Returns:

• self or None if a raw put was done and corresponding new node could not be found.

Examples:

>>> FST('[0, 1, 2, 3]').put('x', 1).src
'[0, x, 2, 3]'

>>> FST('[0, 1, 2, 3]').put('x, y', 1, 3).src
'[0, (x, y), 3]'

>>> FST('[0, 1, 2, 3]').put('x, y', 1, 3, one=False).src
'[0, x, y, 3]'

>>> FST('[0, 1, 2, 3]').put('x, y', 0, 3).src
'[(x, y), 3]'

>>> FST('[0, 1, 2, 3]').put('x, y', -3, 'end', one=False).src
'[0, x, y]'

>>> FST('[0, 1]').put('x, y', 'end').src
'[0, 1, (x, y)]'

>>> FST('[0, 1]').put('x, y', 'end', one=False).src
'[0, 1, x, y]'

>>> print(FST('if 1: i = 1\nelse: j = 2').put('z = -1', 0).src)
if 1:
    z = -1
else: j = 2

>>> print(FST('if 1: i = 1\nelse: j = 2').put('z = -1', 0, 'orelse').src)
if 1: i = 1
else:
    z = -1

>>> print(FST('if 1: i = 1\nelse: j = 2')
...       .put('z = -1\ny = -2\nx = -3', 'orelse', one=False).src)
if 1: i = 1
else:
    z = -1
    y = -2
    x = -3

>>> f = FST('if 1: i = 1\nelse: j = 2')
>>> print(f.put('z = -1', 0, raw=True, to=f.orelse[-1]).root.src)
if 1: z = -1