---
id: api-filters
title: Filters
---

Filters in Bowler are intermediate functions that optionally restrict the set of
syntax tree elements originally matched by [selectors](api-selectors) before being
modified. Matched elements must "pass" all filters to get modified – elements that fail
a filter will be dropped immediately, and will not be tested by subsequent filters.

All filter functions must match this signature:

```python
def some_filter(node: LN, capture: Capture, filename: Filename) -> bool:
    ...
```

Argument | Description
---|---
node | The matched syntax tree element.
capture | Sub-elements captured by the selector pattern.
filename | The file being considered for modification.
return value | `True` if the element should be modified, `False` otherwise.


## Filter Reference

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

### `.filter()`

Add a custom filter function to the query.

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

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

### `.is_filename()`

Restrict modifications to files matching the supplied regular expression[s].
Supports both inclusive and exclusive matches. If both are given, then both must match.

```python
query.is_filename(include: str = None, exclude: str = None)
```

Argument | Description
---|---
include | Only modify files matching the given pattern.
exclude | Only modify files that don't match the given pattern.

### `.is_call()`

Only modify if the matched element is a class, function, or method call. Requires
selector that captures `class_call` or `function_call` similar to
[`.select_function()`](api-selectors#select-function).

```python
query.is_call()
```

### `.is_def()`

Only modify if the matched element is a class, function, or method definition. Requires
selector that captures `class_def` or `function_def` similar to
[`.select_function()`](api-selectors#select-function).

```python
query.is_def()
```

### `.in_class()`

Only modify matched elements belonging to the given class, or to a subclass.
Implies use of `.is_def()`.

```python
query.in_class(class_name: str, include_subclasses: bool = True)
```

Argument | Description
---|---
class_name | Name of class or ancestor class to match.
include_subclasses | When `False`, skips elements on subclasses of `class_name`.
