Modifiers · Bowler

Modifiers in Bowler are functions that modify, add, remove, or replace syntax tree elements originally matched by selectors after elements have passed all filters. Modifications may occur anywhere in the syntax tree, either above or below the matched element, and may include multiple modifications.

All modifier functions must match this signature:

def modifier(node: LN, capture: Capture, filename: Filename) -> Optional[LN]:
    ...

Argument	Description
node	The matched syntax tree element.
capture	Sub-elements captured by the selector pattern.
filename	The file being modified.
return value	Leaf or nodes returned will automatically replace the matched element.

Modifier Reference

All modifiers are accessed as methods on the Query class:

.modify()
.encapsulate()
.rename()
.add_argument()
.modify_argument()
.remove_argument()

Note: Bowler's API is still in a "provisional" phase. The core concepts will likely stay the same, but individual method signatures may change as the tool matures or gains new functionality.

`.modify()`

Add a custom modifier to the query.

query.modify(callback: Callback)

Argument	Description
callback	The custom modifier function.

`.encapsulate()`

Encapsulate a class attribute using @property.

query.encapsulate(internal_name: str = "")

Argument	Description
internal_name	The "internal" name for the underlying attribute. Defaults to `_{old_name}`.

`.rename()`

Rename a matched element to a new name. Requires using a default selector.

query.rename(new_name: str)

Argument	Description
new_name	New name for element.

`.add_argument()`

Add an argument to a function or method, as well as callers. For positional arguments, the default value will be used to update all callers; for keyword arguments, it will be used in the function definition.

Requires use of .select_function or .select_method.

query.add_argument(
    name: str,
    value: str,
    positional: bool = False,
    after: Stringish = SENTINEL,
    type_annotation: Stringish = SENTINEL,
)

Argument	Description
name	The new argument name.
value	Default value for the argument.
positional	If `True`, will be treated as a positional argument, otherwise as a keyword.
after	If `positional = True`, will be placed after this argument. Defaults to the end. Use `START` to place at the beginning.
type_annotation	Optional type annotation for the new argument.

`.modify_argument()`

Modify the specified argument to a function or method, as well as callers.

Requires use of .select_function or .select_method.

query.modify_argument(
    name: str,
    new_name: Stringish = SENTINEL,
    type_annotation: Stringish = SENTINEL,
    default_value: Stringish = SENTINEL,
)

Argument	Description
name	The argument to modify.
new_name	Optional new name for the argument.
type_annotation	Optional type annotation to set. Use `DROP` to remove a type annotation.
default_value	Optional default value to set.

`.remove_argument()`

Remove the specified argument from a function or method, as well as all callers.

Requires use of .select_function or .select_method.

query.remove_argument(name: str)

Argument	Description
name	The argument to remove.