---
id: api-modifiers
title: Modifiers
---

Modifiers in Bowler are functions that modify, add, remove, or replace syntax tree
elements originally matched by [selectors](api-selectors) after elements have passed
all [filters](api-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:

```python
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`](api-query) class:

<AUTOGENERATED_TABLE_OF_CONTENTS>

> 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.

```python
query.modify(callback: Callback)
```

Argument | Description
---|---
callback | The custom modifier function.

### `.encapsulate()`

Encapsulate a class attribute using `@property`.

```python
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.

```python
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`](api-selectors#select-function) or
[`.select_method`](api-selectors#select-method).

```python
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`](api-selectors#select-function) or
[`.select_method`](api-selectors#select-method).

```python
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`](api-selectors#select-function) or
[`.select_method`](api-selectors#select-method).

```python
query.remove_argument(name: str)
```

Argument | Description
---|---
name | The argument to remove.
